plato-sdk 1.0.0__tar.gz

plato_sdk-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv

plato_sdk-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12.8

plato_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: plato-sdk
+Version: 1.0.0
+Summary: Plato SDK
+Author-email: Pranav Putta <pranav@plato.so>, Rob Farlow <rob@plato.so>
+Requires-Python: >=3.8
+Requires-Dist: aiohttp>=3.11.13
+Requires-Dist: build>=1.2.2.post1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: twine>=6.1.0
+Description-Content-Type: text/markdown
+
+# Plato SDK
+
+
+## Usage
+```
+class Task(BaseModel):
+    ...
+
+async with env := plato.make(ENV_ID):
+    cdp_url = env.cdp_url
+    
+    # connect to browser and do modifications
+
+   # get state
+    state_mutations: dict = env.get_state()
+
+    # evaluate
+
+    ...
+
+```

plato_sdk-1.0.0/README.md

@@ -0,0 +1,21 @@
+# Plato SDK
+
+
+## Usage
+```
+class Task(BaseModel):
+    ...
+
+async with env := plato.make(ENV_ID):
+    cdp_url = env.cdp_url
+    
+    # connect to browser and do modifications
+
+   # get state
+    state_mutations: dict = env.get_state()
+
+    # evaluate
+
+    ...
+
+```

plato_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "plato-sdk"
+version = "1.0.0"
+description = "Plato SDK"
+authors = [
+    { name = "Pranav Putta", email = "pranav@plato.so" },
+    {name = "Rob Farlow", email="rob@plato.so"}
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.10.6",
+    "pydantic-settings>=2.8.1",
+    "aiohttp>=3.11.13",
+    "build>=1.2.2.post1",
+    "twine>=6.1.0",
+]
+readme = "README.md"
+requires-python = ">= 3.8"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.rye]
+managed = true
+dev-dependencies = []
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/plato"]

plato_sdk-1.0.0/requirements-dev.lock

@@ -0,0 +1,115 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.11.13
+    # via plato
+aiosignal==1.3.2
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.8.0
+    # via httpx
+attrs==25.2.0
+    # via aiohttp
+build==1.2.2.post1
+    # via plato
+certifi==2025.1.31
+    # via httpcore
+    # via httpx
+    # via requests
+charset-normalizer==3.4.1
+    # via requests
+docutils==0.21.2
+    # via readme-renderer
+frozenlist==1.5.0
+    # via aiohttp
+    # via aiosignal
+h11==0.14.0
+    # via httpcore
+httpcore==1.0.7
+    # via httpx
+httpx==0.28.1
+    # via plato
+id==1.5.0
+    # via twine
+idna==3.10
+    # via anyio
+    # via httpx
+    # via requests
+    # via yarl
+jaraco-classes==3.4.0
+    # via keyring
+jaraco-context==6.0.1
+    # via keyring
+jaraco-functools==4.1.0
+    # via keyring
+keyring==25.6.0
+    # via twine
+markdown-it-py==3.0.0
+    # via rich
+mdurl==0.1.2
+    # via markdown-it-py
+more-itertools==10.6.0
+    # via jaraco-classes
+    # via jaraco-functools
+multidict==6.1.0
+    # via aiohttp
+    # via yarl
+nh3==0.2.21
+    # via readme-renderer
+packaging==24.2
+    # via build
+    # via twine
+propcache==0.3.0
+    # via aiohttp
+    # via yarl
+pydantic==2.10.6
+    # via plato
+    # via pydantic-settings
+pydantic-core==2.27.2
+    # via pydantic
+pydantic-settings==2.8.1
+    # via plato
+pygments==2.19.1
+    # via readme-renderer
+    # via rich
+pyproject-hooks==1.2.0
+    # via build
+python-dotenv==1.0.1
+    # via pydantic-settings
+readme-renderer==44.0
+    # via twine
+requests==2.32.3
+    # via id
+    # via requests-toolbelt
+    # via twine
+requests-toolbelt==1.0.0
+    # via twine
+rfc3986==2.0.0
+    # via twine
+rich==13.9.4
+    # via twine
+sniffio==1.3.1
+    # via anyio
+twine==6.1.0
+    # via plato
+typing-extensions==4.12.2
+    # via anyio
+    # via pydantic
+    # via pydantic-core
+urllib3==2.3.0
+    # via requests
+    # via twine
+yarl==1.18.3
+    # via aiohttp

plato_sdk-1.0.0/requirements.lock

@@ -0,0 +1,115 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+#   generate-hashes: false
+#   universal: false
+
+-e file:.
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.11.13
+    # via plato
+aiosignal==1.3.2
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.8.0
+    # via httpx
+attrs==25.2.0
+    # via aiohttp
+build==1.2.2.post1
+    # via plato
+certifi==2025.1.31
+    # via httpcore
+    # via httpx
+    # via requests
+charset-normalizer==3.4.1
+    # via requests
+docutils==0.21.2
+    # via readme-renderer
+frozenlist==1.5.0
+    # via aiohttp
+    # via aiosignal
+h11==0.14.0
+    # via httpcore
+httpcore==1.0.7
+    # via httpx
+httpx==0.28.1
+    # via plato
+id==1.5.0
+    # via twine
+idna==3.10
+    # via anyio
+    # via httpx
+    # via requests
+    # via yarl
+jaraco-classes==3.4.0
+    # via keyring
+jaraco-context==6.0.1
+    # via keyring
+jaraco-functools==4.1.0
+    # via keyring
+keyring==25.6.0
+    # via twine
+markdown-it-py==3.0.0
+    # via rich
+mdurl==0.1.2
+    # via markdown-it-py
+more-itertools==10.6.0
+    # via jaraco-classes
+    # via jaraco-functools
+multidict==6.1.0
+    # via aiohttp
+    # via yarl
+nh3==0.2.21
+    # via readme-renderer
+packaging==24.2
+    # via build
+    # via twine
+propcache==0.3.0
+    # via aiohttp
+    # via yarl
+pydantic==2.10.6
+    # via plato
+    # via pydantic-settings
+pydantic-core==2.27.2
+    # via pydantic
+pydantic-settings==2.8.1
+    # via plato
+pygments==2.19.1
+    # via readme-renderer
+    # via rich
+pyproject-hooks==1.2.0
+    # via build
+python-dotenv==1.0.1
+    # via pydantic-settings
+readme-renderer==44.0
+    # via twine
+requests==2.32.3
+    # via id
+    # via requests-toolbelt
+    # via twine
+requests-toolbelt==1.0.0
+    # via twine
+rfc3986==2.0.0
+    # via twine
+rich==13.9.4
+    # via twine
+sniffio==1.3.1
+    # via anyio
+twine==6.1.0
+    # via plato
+typing-extensions==4.12.2
+    # via anyio
+    # via pydantic
+    # via pydantic-core
+urllib3==2.3.0
+    # via requests
+    # via twine
+yarl==1.18.3
+    # via aiohttp

plato_sdk-1.0.0/src/plato/client.py

@@ -0,0 +1,203 @@
+from typing import Optional, Dict, Any
+import aiohttp
+from plato.config import get_config
+from plato.models import PlatoTask, PlatoEnvironment
+
+config = get_config()
+
+class PlatoClient:
+    """Client for interacting with the Plato API.
+
+    This class provides methods to create and manage Plato environments, handle API authentication,
+    and manage HTTP sessions.
+
+    Attributes:
+        api_key (str): The API key used for authentication with Plato API.
+        base_url (str): The base URL of the Plato API.
+        http_session (Optional[aiohttp.ClientSession]): The aiohttp session for making HTTP requests.
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        """Initialize a new PlatoClient.
+
+        Args:
+            api_key (Optional[str]): The API key for authentication. If not provided,
+                falls back to the key from config.
+        """
+        self.api_key = api_key or config.api_key
+        self.base_url = config.base_url
+        self._http_session: Optional[aiohttp.ClientSession] = None
+
+    @property
+    def http_session(self) -> aiohttp.ClientSession:
+        """Get or create an aiohttp client session.
+
+        Returns:
+            aiohttp.ClientSession: The active HTTP client session.
+        """
+        if self._http_session is None or self._http_session.closed:
+            self._http_session = aiohttp.ClientSession()
+        return self._http_session
+
+    async def close(self):
+        """Close the aiohttp client session if it exists."""
+        if self._http_session is not None and not self._http_session.closed:
+            await self._http_session.close()
+            self._http_session = None
+
+    async def make_environment(self, env_id: str) -> PlatoEnvironment:
+        """Create a new Plato environment for the given task.
+
+        Args:
+            task (PlatoTask): The task to create an environment for.
+
+        Returns:
+            PlatoEnvironment: The created environment instance.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.post(
+            f"{self.base_url}/env/make",
+            json={"config": {
+                "type": "browser_sim",
+                "env_id": env_id,
+                "sim_connection_type": "fastapi"
+            }},
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            data = await response.json()
+            return PlatoEnvironment(
+                client=self,
+                id=data["job_id"]
+            )
+
+    async def get_job_status(self, job_id: str) -> Dict[str, Any]:
+        """Get the status of a job.
+
+        Args:
+            job_id (str): The ID of the job to check.
+
+        Returns:
+            Dict[str, Any]: The job status information.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.get(
+            f"{self.base_url}/env/{job_id}/status",
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            return await response.json()
+
+    async def get_cdp_url(self, job_id: str) -> str:
+        """Get the Chrome DevTools Protocol URL for a job.
+
+        Args:
+            job_id (str): The ID of the job to get the CDP URL for.
+
+        Returns:
+            str: The CDP URL for the job.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.get(
+            f"{self.base_url}/env/{job_id}/cdp_url",
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            data = await response.json()
+            return data["cdp_url"]
+
+    async def close_environment(self, job_id: str) -> Dict[str, Any]:
+        """Close an environment.
+
+        Args:
+            job_id (str): The ID of the job to close.
+
+        Returns:
+            Dict[str, Any]: The response from the server.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.post(
+            f"{self.base_url}/env/{job_id}/close",
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            return await response.json()
+
+    async def reset_environment(self, job_id: str, task: Optional[PlatoTask] = None) -> Dict[str, Any]:
+        """Reset an environment with an optional new task.
+
+        Args:
+            job_id (str): The ID of the job to reset.
+            task (Optional[PlatoTask]): Optional new task for the environment.
+
+        Returns:
+            Dict[str, Any]: The response from the server.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        params = {"task": task.dict() if task else None}
+        async with self.http_session.post(
+            f"{self.base_url}/env/{job_id}/reset",
+            headers=headers,
+        ) as response:
+            response.raise_for_status()
+            return await response.json()
+
+    async def get_environment_state(self, job_id: str) -> Dict[str, Any]:
+        """Get the current state of an environment.
+
+        Args:
+            job_id (str): The ID of the job to get state for.
+
+        Returns:
+            Dict[str, Any]: The current state of the environment.
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.get(
+            f"{self.base_url}/env/{job_id}/state",
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            return await response.json()
+
+    async def get_worker_ready(self, job_id: str) -> Dict[str, Any]:
+        """Check if the worker for this job is ready and healthy.
+
+        Args:
+            job_id (str): The ID of the job to check.
+
+        Returns:
+            Dict[str, Any]: The worker ready status information including:
+                - ready (bool): Whether the worker is ready
+                - worker_ip (Optional[str]): The worker's IP if ready
+                - worker_port (Optional[int]): The worker's port if ready
+                - health_status (Optional[Dict]): The worker's health status if ready
+                - error (Optional[str]): Error message if not ready
+
+        Raises:
+            aiohttp.ClientError: If the API request fails.
+        """
+        headers = {"X-API-Key": self.api_key}
+        async with self.http_session.get(
+            f"{self.base_url}/env/{job_id}/worker_ready",
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            return await response.json()

plato_sdk-1.0.0/src/plato/config.py

@@ -0,0 +1,22 @@
+"""Configuration settings for the Plato client."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+
+class Config(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_prefix="PLATO_")
+    base_url: str = Field(
+        default="http://localhost:25565/api",
+        description="Base URL for the Plato API",
+        validation_alias="PLATO_BASE_URL    ",
+    )
+    api_key: str = Field(
+        default="",
+        description="API key for the Plato API",
+        validation_alias="PLATO_API_KEY",
+    )
+
+@lru_cache
+def get_config() -> Config:
+    return Config()

plato_sdk-1.0.0/src/plato/models/__init__.py

@@ -0,0 +1,4 @@
+from .task import PlatoTask
+from .env import PlatoEnvironment
+
+__all__ = ["PlatoTask", "PlatoEnvironment"]

plato_sdk-1.0.0/src/plato/models/env.py

@@ -0,0 +1,158 @@
+from pydantic import BaseModel, Field
+from plato.models import PlatoTask
+from typing import List, Optional, Type, Dict, Any
+import time
+import asyncio
+from aiohttp import ClientError
+
+
+class PlatoEnvironment:
+    """A base environment class for Plato that handles task execution and state management.
+
+    This class provides the core interface for creating, managing, and interacting with
+    task environments. It implements an async context manager pattern and defines the
+    basic contract that all Plato environments must fulfill.
+
+    Attributes:
+        _client (PlatoClient): The client instance for interacting with the environment
+        _current_task (Optional[PlatoTask]): The task currently being executed
+        id (str): Unique identifier for this environment instance (job ID)
+    """
+
+    _current_task: Optional[PlatoTask] = Field(
+        description="The current task for the environment", default=None
+    )
+    _client: "PlatoClient" = Field(description="The client for the environment")
+    id: str = Field(description="The ID for the environment (job ID)")
+
+    def __init__(self, client: "PlatoClient", id: str):
+        self._client = client
+        self.id = id
+
+    async def wait_for_ready(self, timeout: Optional[float] = None) -> None:
+        """Wait for the environment to be ready.
+
+        This method checks both the job status and worker health until everything is ready.
+
+        Args:
+            timeout (Optional[float]): Maximum time to wait in seconds before raising an error.
+                                     If None, will wait indefinitely.
+
+        Raises:
+            RuntimeError: If the environment fails to start within the timeout period.
+        """
+        start_time = time.time()
+
+        # wait for the job to be running
+        while True:
+            status = await self._client.get_job_status(self.id)
+            if status["status"].lower() == "running":
+                break
+            await asyncio.sleep(0.1)
+            if timeout and time.time() - start_time > timeout:
+                raise RuntimeError(
+                    "Environment failed to start - job never entered running state"
+                )
+
+        # wait for the worker to be ready and healthy
+        while True:
+            worker_status = await self._client.get_worker_ready(self.id)
+            if worker_status["ready"]:
+                break
+            await asyncio.sleep(0.1)
+            if timeout and time.time() - start_time > timeout:
+                error_msg = worker_status.get("error", "Unknown error")
+                raise RuntimeError(
+                    f"Environment failed to start - worker not ready: {error_msg}"
+                )
+
+        # wait for the cdp url to be ready
+        while True:
+            try:
+                cdp_url = await self._client.get_cdp_url(self.id)
+                if cdp_url:
+                    break
+            except ClientError as e:
+                await asyncio.sleep(0.1)
+            if timeout and time.time() - start_time > timeout:
+                raise RuntimeError("Environment failed to start - cdp url not ready")
+
+    async def __aenter__(self):
+        """Enter the async context manager.
+
+        Calls make() to initialize the environment and returns self.
+
+        Returns:
+            PlatoEnvironment: The initialized environment instance.
+        """
+        await self.wait_for_ready()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[Type[BaseException]],
+    ) -> None:
+        """Exit the async context manager.
+
+        Performs cleanup by calling close() when the context manager exits.
+
+        Args:
+            exc_type: The type of the exception that was raised, if any
+            exc_val: The instance of the exception that was raised, if any
+            exc_tb: The traceback of the exception that was raised, if any
+        """
+        await self.close()
+
+    async def get_cdp_url(self) -> str:
+        """Get the Chrome DevTools Protocol URL for this environment's session.
+
+        Returns:
+            str: The CDP URL for connecting to this environment's browser session.
+        """
+        return await self._client.get_cdp_url(self.id)
+
+    async def reset(self, task: Optional[PlatoTask] = None) -> None:
+        """Reset the environment with an optional new task.
+
+        Args:
+            task (Optional[PlatoTask]): The new task to set up the environment for.
+        """
+        await self._client.reset_environment(self.id, task)
+        if task:
+            self._current_task = task
+
+    async def get_state(self) -> Dict[str, Any]:
+        """Get the current state of the environment.
+
+        Returns:
+            Dict[str, Any]: A dictionary representing the current state of the environment.
+        """
+        return await self._client.get_environment_state(self.id)
+
+    async def get_state_mutations(self) -> List[Dict[str, Any]]:
+        """Get a list of state mutations that have occurred in the environment.
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries representing state changes.
+        """
+        state = await self.get_state()
+        return state.get("mutations", [])
+
+    async def evaluate(self) -> bool:
+        """Evaluate whether the current task has been completed successfully.
+
+        Returns:
+            bool: True if the task is completed successfully, False otherwise.
+        """
+        state = await self.get_state()
+        return state.get("completed", False)
+
+    async def close(self) -> None:
+        """Clean up and close the environment.
+
+        This method handles cleanup of resources by closing the environment
+        through the API client.
+        """
+        await self._client.close_environment(self.id)

plato_sdk-1.0.0/src/plato/models/task.py

@@ -0,0 +1,53 @@
+from pydantic import BaseModel
+from typing import Optional, Literal, List
+
+
+class BasePlatoEvalConfig(BaseModel):
+    """Base configuration class for Plato evaluation settings.
+
+    This class serves as the base configuration for different types of evaluation
+    methods in the Plato system.
+
+    Attributes:
+        type (Literal["base", "state_mutation_match"]): The type of evaluation configuration.
+            Can be either "base" or "state_mutation_match".
+    """
+    type: Literal["base", "state_mutation_match"]
+
+
+class StateMutationMatchEvalConfig(BasePlatoEvalConfig):
+    """Configuration for state mutation matching evaluation.
+
+    This class defines the configuration for evaluating tasks based on matching
+    state mutations. It inherits from BasePlatoEvalConfig and specifies
+    state mutations that should be matched during evaluation.
+
+    Attributes:
+        type (Literal["state_mutation_match"]): The type of evaluation, fixed as
+            "state_mutation_match" for this configuration.
+        state_mutations (List[dict]): A list of state mutation specifications that
+            define the expected changes in state during task execution.
+    """
+    type: Literal["state_mutation_match"] = "state_mutation_match"
+    state_mutations: List[dict]
+
+
+class PlatoTask(BaseModel):
+    """Represents a task in the Plato system.
+
+    This class defines the structure of a task, including its name, metadata,
+    initial state, and evaluation configuration.
+
+    Attributes:
+        name (Optional[str]): The name of the task. Defaults to None.
+        metadata (Optional[dict]): Additional metadata associated with the task.
+            Defaults to None.
+        initial_state (Optional[dict]): The initial state of the task before
+            execution. Defaults to None.
+        eval_config (Optional[BasePlatoEvalConfig]): The evaluation configuration
+            for the task. Defaults to None.
+    """
+    name: Optional[str] = None
+    metadata: Optional[dict] = None
+    initial_state: Optional[dict] = None
+    eval_config: Optional[BasePlatoEvalConfig] = None

plato_sdk-1.0.0/src/plato/test/test_env.py

@@ -0,0 +1,42 @@
+import asyncio
+from plato.client import PlatoClient
+from plato.models import PlatoEnvironment, PlatoTask
+
+async def test_environment_lifecycle():
+    """Test the lifecycle of a Plato environment including creation, reset, and closure."""
+    # Initialize the client
+    client = PlatoClient()
+    
+    # Create a sample task
+    task = PlatoTask(
+        name="example_task",
+        metadata={"type": "test"},
+        initial_state={"url": "https://example.com"}
+    )
+    
+    # Create and initialize the environment
+    env = await client.make_environment("doordash")
+    
+    try:
+        # Wait for the environment to be ready
+        await env.wait_for_ready(timeout=30.0)
+        
+        # Get the CDP URL for browser connection
+        cdp_url = await env.get_cdp_url()
+        print(f"Environment ready with CDP URL: {cdp_url}")
+        
+        # Reset the environment with a new task
+        await env.reset()
+        print("Environment reset with new task")
+        breakpoint()
+
+    finally:
+        # Always ensure we close the environment
+        await env.close()
+        print("Environment closed")
+        # Close the client to cleanup aiohttp session
+        await client.close()
+        print("Client closed")
+
+if __name__ == "__main__":
+    asyncio.run(test_environment_lifecycle())