plato-sdk 0.1.0a1__tar.gz

plato_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.2
+Name: plato-sdk
+Version: 0.1.0a1
+Summary: Plato SDK
+Requires-Python: >=3.12.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.11.13
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pydantic-settings>=2.8.1
+
+# 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-0.1.0a1/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-0.1.0a1/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "plato-sdk"
+version = "0.1.0a1"
+description = "Plato SDK"
+readme = "README.md"
+requires-python = ">=3.12.8"
+dependencies = [
+    "aiohttp>=3.11.13",
+    "pydantic>=2.10.6",
+    "pydantic-settings>=2.8.1",
+]

plato_sdk-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plato_sdk-0.1.0a1/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-0.1.0a1/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-0.1.0a1/src/plato/models/__init__.py

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

plato_sdk-0.1.0a1/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-0.1.0a1/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-0.1.0a1/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()) 

plato_sdk-0.1.0a1/src/plato_sdk.egg-info/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.2
+Name: plato-sdk
+Version: 0.1.0a1
+Summary: Plato SDK
+Requires-Python: >=3.12.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.11.13
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pydantic-settings>=2.8.1
+
+# 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-0.1.0a1/src/plato_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+src/plato/client.py
+src/plato/config.py
+src/plato/models/__init__.py
+src/plato/models/env.py
+src/plato/models/task.py
+src/plato/test/test_env.py
+src/plato/test/test_run.py
+src/plato_sdk.egg-info/PKG-INFO
+src/plato_sdk.egg-info/SOURCES.txt
+src/plato_sdk.egg-info/dependency_links.txt
+src/plato_sdk.egg-info/requires.txt
+src/plato_sdk.egg-info/top_level.txt

plato_sdk-0.1.0a1/src/plato_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

plato_sdk-0.1.0a1/src/plato_sdk.egg-info/requires.txt

@@ -0,0 +1,3 @@
+aiohttp>=3.11.13
+pydantic>=2.10.6
+pydantic-settings>=2.8.1

plato_sdk-0.1.0a1/src/plato_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+plato