appworld-sdk 0.1.0__py3-none-any.whl

appworld_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""App World SDK — lightweight client for RL & Eval on the App World platform.
+
+Install: ``pip install appworld-sdk``
+
+Dependencies: requests, numpy, Pillow, gymnasium (no platform internals).
+"""
+
+from appworld_sdk.agent import BaseAgent
+from appworld_sdk.client import (
+    AppWorldClient,
+    LocalEvalBatchResult,
+    LocalEvalResult,
+    RunResult,
+)
+from appworld_sdk.env import RemoteAppWorldEnv, RemoteAppWorldEvalEnv
+from appworld_sdk.errors import (
+    AppWorldAPIError,
+    AppWorldError,
+    EnvironmentNotReady,
+    SessionExpired,
+)
+
+__all__ = [
+    "AppWorldClient",
+    "BaseAgent",
+    "RemoteAppWorldEnv",
+    "RemoteAppWorldEvalEnv",
+    "RunResult",
+    "LocalEvalResult",
+    "LocalEvalBatchResult",
+    "AppWorldError",
+    "AppWorldAPIError",
+    "EnvironmentNotReady",
+    "SessionExpired",
+]

appworld_sdk/agent.py

@@ -0,0 +1,43 @@
+"""Base agent protocol for client-side eval loops."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+import numpy as np
+
+
+@runtime_checkable
+class BaseAgent(Protocol):
+    """Agent that decides actions based on observations.
+
+    Users implement this protocol to plug in custom models.
+    The SDK never imports any specific LLM provider — that's the
+    user's responsibility.
+
+    Example::
+
+        class MyAgent:
+            def predict(self, *, screenshot, goal, **kw) -> dict:
+                # call your own model
+                return {"action_type": 0, "x": 0.5, "y": 0.5, ...}
+    """
+
+    def predict(
+        self,
+        *,
+        screenshot: np.ndarray,
+        goal: str,
+        task_name: str,
+        task_description: str,
+        app_names: list[str],
+        step_index: int,
+        max_steps: int,
+        history: list[str],
+    ) -> dict[str, Any]:
+        """Return an action dict.
+
+        Expected keys: action_type, x, y, text, direction, app_name.
+        Optional key: description (used for history logging).
+        """
+        ...

appworld_sdk/client.py

@@ -0,0 +1,534 @@
+"""HTTP client for the App World platform.
+
+This is a pure API client — it knows nothing about tasks, adapters,
+rewards, or LLM providers.  All heavy lifting happens on the platform
+side; the client just sends HTTP requests and returns results.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import time
+from dataclasses import dataclass, field
+from io import BytesIO
+from typing import Any
+
+import numpy as np
+import requests
+from PIL import Image
+
+from appworld_sdk.agent import BaseAgent
+from appworld_sdk.env import RemoteAppWorldEnv, RemoteAppWorldEvalEnv
+from appworld_sdk.errors import (
+    AppWorldAPIError,
+    EnvironmentNotReady,
+    SessionExpired,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _decode_screenshot(data_url: str) -> np.ndarray:
+    """Decode a data:image/... URL into an RGB numpy array."""
+    _, payload = data_url.split(",", 1)
+    binary = base64.b64decode(payload)
+    return np.array(Image.open(BytesIO(binary)).convert("RGB"))
+
+
+# ---------------------------------------------------------------------------
+# Result data classes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RunResult:
+    id: str
+    name: str
+    status: str
+    type: str
+    environment_id: str
+    success_rate: float | None
+    avg_steps: float | None
+    results: list[dict[str, Any]]
+    raw: dict[str, Any]
+
+
+@dataclass
+class LocalEvalResult:
+    """Result of a single-task client-side eval."""
+
+    task_name: str
+    status: str
+    steps: int
+    reward: float
+    history: list[str]
+    terminated: bool
+    truncated: bool
+
+
+@dataclass
+class LocalEvalBatchResult:
+    """Aggregated result of a multi-task local eval."""
+
+    task_results: list[LocalEvalResult] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        if not self.task_results:
+            return 0.0
+        return sum(1 for r in self.task_results if r.status == "completed") / len(
+            self.task_results
+        )
+
+    @property
+    def avg_steps(self) -> float:
+        if not self.task_results:
+            return 0.0
+        return sum(r.steps for r in self.task_results) / len(self.task_results)
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class AppWorldClient:
+    """Thin API client for the App World platform.
+
+    Usage::
+
+        client = AppWorldClient(api_key="sk-xxx", base_url="https://api.appworld.dev")
+
+        # Browse catalog
+        tasks = client.list_tasks()
+
+        # Create environment (allocates device resources)
+        env_info = client.create_environment(
+            task_ids=["FennoteCreateNote", "FennoteDeleteNote"],
+        )
+        env_id = env_info["id"]
+
+        # Get a Gymnasium-compatible env (bound to environment, NOT to a task)
+        env = client.make_env(env_id=env_id, env_type="eval")
+
+        # Run multiple tasks on the same environment
+        for task in ["FennoteCreateNote", "FennoteDeleteNote"]:
+            obs, info = env.reset(task_name=task)
+            done = False
+            while not done:
+                action = my_agent.predict(screenshot=obs["screenshot"], goal=obs["goal"], ...)
+                obs, reward, terminated, truncated, info = env.step(action)
+                done = terminated or truncated
+
+        env.close()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://127.0.0.1:8000",
+        timeout: float = 60.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _raise_for_status(self, response: requests.Response) -> None:
+        if response.ok:
+            return
+        detail = ""
+        try:
+            body = response.json()
+            detail = body.get("detail", "")
+        except Exception:
+            detail = response.text[:200]
+        if response.status_code == 503:
+            raise EnvironmentNotReady("unknown", detail=detail)
+        if response.status_code == 410:
+            raise SessionExpired("unknown", detail=detail)
+        raise AppWorldAPIError(
+            detail or response.reason or "API error",
+            status_code=response.status_code,
+            detail=detail,
+        )
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = requests.get(
+            f"{self.base_url}{path}",
+            headers=self.headers,
+            params=params,
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def _post(self, path: str, payload: dict[str, Any]) -> Any:
+        response = requests.post(
+            f"{self.base_url}{path}",
+            headers=self.headers,
+            json=payload,
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    def _delete(self, path: str) -> Any:
+        response = requests.delete(
+            f"{self.base_url}{path}",
+            headers=self.headers,
+            timeout=self.timeout,
+        )
+        self._raise_for_status(response)
+        return response.json()
+
+    # ------------------------------------------------------------------
+    # Catalog
+    # ------------------------------------------------------------------
+
+    def list_apps(self, **filters: Any) -> list[dict[str, Any]]:
+        return self._get("/api/v1/apps", params=filters)["items"]
+
+    def list_tasks(self, **filters: Any) -> list[dict[str, Any]]:
+        return self._get("/api/v1/tasks", params=filters)["items"]
+
+    def get_task(self, task_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/tasks/{task_id}")
+
+    # ------------------------------------------------------------------
+    # Environments
+    # ------------------------------------------------------------------
+
+    def list_environments(self, **filters: Any) -> list[dict[str, Any]]:
+        return self._get("/api/v1/environments", params=filters)["items"]
+
+    def create_environment(
+        self,
+        task_ids: list[str],
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        payload = {"task_ids": task_ids, "name": name or "sdk-environment"}
+        return self._post("/api/v1/environments", payload)
+
+    def get_environment(self, env_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/environments/{env_id}")
+
+    def delete_environment(self, env_id: str) -> dict[str, Any]:
+        return self._delete(f"/api/v1/environments/{env_id}")
+
+    def get_environment_status(self, env_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/environments/{env_id}/status")
+
+    def stop_environment(self, env_id: str) -> dict[str, Any]:
+        return self._post(f"/api/v1/environments/{env_id}/stop", {})
+
+    def restart_environment(self, env_id: str) -> dict[str, Any]:
+        return self._post(f"/api/v1/environments/{env_id}/restart", {})
+
+    # ------------------------------------------------------------------
+    # Low-level SDK env endpoints (for advanced usage)
+    # ------------------------------------------------------------------
+
+    def sdk_reset(
+        self,
+        *,
+        env_id: str,
+        task_name: str,
+        env_type: str = "eval",
+    ) -> dict[str, Any]:
+        return self._post("/api/v1/sdk/env/reset", {
+            "env_id": env_id,
+            "task_name": task_name,
+            "env_type": env_type,
+        })
+
+    def sdk_step(self, *, session_id: str, action: Any) -> dict[str, Any]:
+        return self._post("/api/v1/sdk/env/step", {
+            "session_id": session_id,
+            "action": action,
+        })
+
+    def sdk_close(self, *, session_id: str) -> dict[str, Any]:
+        return self._post("/api/v1/sdk/env/close", {"session_id": session_id})
+
+    # ------------------------------------------------------------------
+    # Gymnasium-compatible remote environment
+    # ------------------------------------------------------------------
+
+    def make_env(
+        self,
+        *,
+        env_id: str,
+        env_type: str = "eval",
+    ) -> RemoteAppWorldEnv | RemoteAppWorldEvalEnv:
+        """Create a Gymnasium-compatible remote environment.
+
+        The env is bound to an environment (device resources), NOT to a
+        specific task.  Pass ``task_name`` to ``env.reset()`` to start
+        each task.
+
+        Args:
+            env_id: Environment ID from ``create_environment()``.
+            env_type: ``"rl"`` or ``"eval"``.
+
+        Returns:
+            RemoteAppWorldEnv (rl) or RemoteAppWorldEvalEnv (eval).
+        """
+        if env_type == "rl":
+            return RemoteAppWorldEnv(
+                api_key=self.api_key,
+                base_url=self.base_url,
+                env_id=env_id,
+            )
+        if env_type == "eval":
+            return RemoteAppWorldEvalEnv(
+                api_key=self.api_key,
+                base_url=self.base_url,
+                env_id=env_id,
+            )
+        raise ValueError(f"env_type must be 'rl' or 'eval', got '{env_type}'")
+
+    # ------------------------------------------------------------------
+    # Runs (server-side eval)
+    # ------------------------------------------------------------------
+
+    def list_runs(self, **filters: Any) -> list[dict[str, Any]]:
+        return self._get("/api/v1/runs", params=filters)["items"]
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        return self._get(f"/api/v1/runs/{run_id}")
+
+    def create_run(
+        self,
+        environment_id: str,
+        run_type: str,
+        tasks: list[str],
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post("/api/v1/runs", {
+            "environment_id": environment_id,
+            "type": run_type,
+            "tasks": tasks,
+            "name": name,
+        })
+
+    def wait_for_run(
+        self,
+        run_id: str,
+        poll_interval: float = 0.2,
+        timeout: float = 20.0,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while True:
+            run = self.get_run(run_id)
+            if run["status"] in {"completed", "failed", "stopped"}:
+                return run
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Run '{run_id}' did not finish within {timeout} seconds"
+                )
+            time.sleep(poll_interval)
+
+    def run_eval(
+        self,
+        env_id: str,
+        tasks: list[str],
+        model_provider: str,
+        model_api_key: str,
+        model_name: str | None = None,
+        name: str | None = None,
+        wait: bool = True,
+        poll_interval: float = 0.2,
+        timeout: float = 20.0,
+        max_steps: int = 15,
+    ) -> RunResult:
+        """Submit an eval run to the platform (server-side execution).
+
+        The platform handles LLM calls and environment interactions.
+        The model API key is sent to the server for this execution mode.
+        """
+        payload: dict[str, Any] = {
+            "environment_id": env_id,
+            "type": "eval",
+            "tasks": tasks,
+            "name": name,
+            "model_provider": model_provider,
+            "model_api_key": model_api_key,
+            "max_steps": max_steps,
+        }
+        if model_name:
+            payload["model_name"] = model_name
+        run = self._post("/api/v1/runs", payload)
+        if wait:
+            run = self.wait_for_run(
+                run["id"], poll_interval=poll_interval, timeout=timeout,
+            )
+        return self._to_run_result(run)
+
+    # ------------------------------------------------------------------
+    # Local eval (LLM runs on user side, env interactions via API)
+    # ------------------------------------------------------------------
+
+    def run_local_eval(
+        self,
+        env_id: str,
+        tasks: list[str],
+        agent: BaseAgent,
+        max_steps: int = 15,
+    ) -> LocalEvalBatchResult:
+        """Local eval: LLM calls happen on the client side.
+
+        The agent's API key never leaves the local process.  The server
+        only handles environment interactions (screenshots, actions, state).
+
+        Args:
+            env_id: Environment ID from ``create_environment()``.
+            tasks: List of task names to evaluate.
+            agent: An object implementing ``BaseAgent.predict()``.
+            max_steps: Maximum steps per task.
+        """
+        if not isinstance(agent, BaseAgent):
+            raise TypeError(
+                f"agent must implement BaseAgent.predict(), got {type(agent).__name__}"
+            )
+
+        batch = LocalEvalBatchResult()
+        for task_name in tasks:
+            try:
+                result = self._run_local_eval_task(
+                    env_id=env_id,
+                    task_name=task_name,
+                    agent=agent,
+                    max_steps=max_steps,
+                )
+            except Exception as exc:
+                logger.warning("Task %s failed: %s", task_name, exc)
+                result = LocalEvalResult(
+                    task_name=task_name,
+                    status="failed",
+                    steps=0,
+                    reward=0.0,
+                    history=[],
+                    terminated=False,
+                    truncated=False,
+                )
+            batch.task_results.append(result)
+        return batch
+
+    def _run_local_eval_task(
+        self,
+        env_id: str,
+        task_name: str,
+        agent: BaseAgent,
+        max_steps: int,
+    ) -> LocalEvalResult:
+        """Run a single task with client-side LLM inference."""
+        task_info = self.get_task(task_name)
+        task_description = task_info.get("description", "")
+        app_names = task_info.get("app_names", [])
+
+        reset_payload = self._post("/api/v1/sdk/env/reset", {
+            "env_id": env_id,
+            "task_name": task_name,
+            "env_type": "eval",
+        })
+        session_id = reset_payload["session_id"]
+        observation = reset_payload["observation"]
+        goal = observation.get("goal", task_description)
+
+        history: list[str] = []
+        total_reward = 0.0
+        steps_taken = 0
+        terminated = False
+        truncated = False
+
+        try:
+            for step_index in range(1, max_steps + 1):
+                screenshot = _decode_screenshot(observation["screenshot"])
+
+                action = agent.predict(
+                    screenshot=screenshot,
+                    goal=goal,
+                    task_name=task_name,
+                    task_description=task_description,
+                    app_names=app_names,
+                    step_index=step_index,
+                    max_steps=max_steps,
+                    history=history,
+                )
+
+                description = action.get(
+                    "description", action.get("action_type", "action"),
+                )
+                history.append(str(description))
+
+                logger.info(
+                    "step %d/%d: %s (%.2f, %.2f) %s",
+                    step_index,
+                    max_steps,
+                    action.get("action_type"),
+                    action.get("x", 0),
+                    action.get("y", 0),
+                    description,
+                )
+
+                step_payload = self._post("/api/v1/sdk/env/step", {
+                    "session_id": session_id,
+                    "action": action,
+                })
+
+                total_reward = float(step_payload["reward"])
+                terminated = bool(step_payload["terminated"])
+                truncated = bool(step_payload["truncated"])
+                steps_taken = step_index
+
+                if terminated or truncated:
+                    break
+
+                observation = step_payload["observation"]
+                goal = observation.get("goal", goal)
+
+        finally:
+            try:
+                self._post("/api/v1/sdk/env/close", {"session_id": session_id})
+            except Exception:
+                pass
+
+        status = "completed" if terminated or total_reward >= 1.0 else "failed"
+        return LocalEvalResult(
+            task_name=task_name,
+            status=status,
+            steps=steps_taken,
+            reward=total_reward,
+            history=history,
+            terminated=terminated,
+            truncated=truncated,
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _to_run_result(self, payload: dict[str, Any]) -> RunResult:
+        return RunResult(
+            id=payload["id"],
+            name=payload["name"],
+            status=payload["status"],
+            type=payload["type"],
+            environment_id=payload["environment_id"],
+            success_rate=payload.get("success_rate"),
+            avg_steps=payload.get("avg_steps"),
+            results=payload.get("tasks", []),
+            raw=payload,
+        )

appworld_sdk/env.py

@@ -0,0 +1,194 @@
+"""Remote Gymnasium-compatible environments backed by the App World API.
+
+The env is bound to an *environment* (device/container resources),
+NOT to a specific task.  ``task_name`` is passed at ``reset()`` time,
+so one env object can run multiple tasks sequentially — the typical
+multi-task eval workflow.
+"""
+
+from __future__ import annotations
+
+import base64
+from io import BytesIO
+from typing import Any
+
+import numpy as np
+import requests
+from PIL import Image
+from gymnasium import spaces
+
+from appworld_sdk.errors import AppWorldAPIError, EnvironmentNotReady, SessionExpired
+
+
+def _decode_data_url_png(data_url: str) -> np.ndarray:
+    _, payload = data_url.split(",", 1)
+    binary = base64.b64decode(payload)
+    return np.array(Image.open(BytesIO(binary)).convert("RGB"))
+
+
+def _raise_for_status(response: requests.Response) -> None:
+    """Convert HTTP errors to SDK exceptions."""
+    if response.ok:
+        return
+    detail = ""
+    try:
+        body = response.json()
+        detail = body.get("detail", "")
+    except Exception:
+        detail = response.text[:200]
+    if response.status_code == 503:
+        raise EnvironmentNotReady("unknown", detail=detail)
+    if response.status_code == 410:
+        raise SessionExpired("unknown", detail=detail)
+    raise AppWorldAPIError(
+        detail or response.reason or "API error",
+        status_code=response.status_code,
+        detail=detail,
+    )
+
+
+class _RemoteBaseEnv:
+    """Shared HTTP plumbing for remote environments."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        env_id: str,
+        env_type: str,
+        timeout: float = 180.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.env_id = env_id
+        self.env_type = env_type
+        self.timeout = timeout
+        self.session_id: str | None = None
+        self.current_task: str | None = None
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        response = requests.post(
+            f"{self.base_url}{path}",
+            headers=self.headers,
+            json=payload,
+            timeout=self.timeout,
+        )
+        _raise_for_status(response)
+        return response.json()
+
+    def close(self) -> None:
+        if self.session_id is None:
+            return
+        try:
+            self._post("/api/v1/sdk/env/close", {"session_id": self.session_id})
+        except Exception:
+            pass
+        self.session_id = None
+        self.current_task = None
+
+
+class RemoteAppWorldEnv(_RemoteBaseEnv):
+    """RL environment (5 discrete actions, screenshot observation)."""
+
+    def __init__(self, api_key: str, base_url: str, env_id: str):
+        super().__init__(api_key=api_key, base_url=base_url, env_id=env_id, env_type="rl")
+        self.observation_space = spaces.Box(low=0, high=255, shape=(320, 192, 3), dtype=np.uint8)
+        self.action_space = spaces.MultiDiscrete([5, 100, 100, 4])
+
+    def reset(
+        self,
+        *,
+        task_name: str,
+        seed: int | None = None,
+        options: dict | None = None,
+    ) -> tuple[np.ndarray, dict]:
+        # Close previous session if any
+        self.close()
+
+        payload = self._post("/api/v1/sdk/env/reset", {
+            "env_id": self.env_id,
+            "task_name": task_name,
+            "env_type": "rl",
+        })
+        self.session_id = payload["session_id"]
+        self.current_task = task_name
+        return _decode_data_url_png(payload["observation"]), payload["info"]
+
+    def step(self, action: np.ndarray) -> tuple[np.ndarray, float, bool, bool, dict]:
+        if self.session_id is None:
+            raise RuntimeError("reset() must be called before step()")
+        payload = self._post("/api/v1/sdk/env/step", {
+            "session_id": self.session_id,
+            "action": np.asarray(action).tolist(),
+        })
+        return (
+            _decode_data_url_png(payload["observation"]),
+            float(payload["reward"]),
+            bool(payload["terminated"]),
+            bool(payload["truncated"]),
+            payload["info"],
+        )
+
+
+class RemoteAppWorldEvalEnv(_RemoteBaseEnv):
+    """Eval environment (7 actions incl. text input, dict observation)."""
+
+    def __init__(self, api_key: str, base_url: str, env_id: str):
+        super().__init__(api_key=api_key, base_url=base_url, env_id=env_id, env_type="eval")
+        self.observation_space = spaces.Dict({
+            "screenshot": spaces.Box(low=0, high=255, shape=(320, 192, 3), dtype=np.uint8),
+            "goal": spaces.Text(max_length=500),
+        })
+        self.action_space = spaces.Dict({
+            "action_type": spaces.Discrete(7),
+            "x": spaces.Box(0.0, 1.0, shape=(), dtype=np.float32),
+            "y": spaces.Box(0.0, 1.0, shape=(), dtype=np.float32),
+            "text": spaces.Text(max_length=200),
+            "direction": spaces.Discrete(4),
+        })
+
+    def reset(
+        self,
+        *,
+        task_name: str,
+        seed: int | None = None,
+        options: dict | None = None,
+    ) -> tuple[dict[str, Any], dict]:
+        # Close previous session if any
+        self.close()
+
+        payload = self._post("/api/v1/sdk/env/reset", {
+            "env_id": self.env_id,
+            "task_name": task_name,
+            "env_type": "eval",
+        })
+        self.session_id = payload["session_id"]
+        self.current_task = task_name
+        observation = payload["observation"]
+        return (
+            {"screenshot": _decode_data_url_png(observation["screenshot"]), "goal": observation["goal"]},
+            payload["info"],
+        )
+
+    def step(self, action: dict[str, Any]) -> tuple[dict[str, Any], float, bool, bool, dict]:
+        if self.session_id is None:
+            raise RuntimeError("reset() must be called before step()")
+        payload = self._post("/api/v1/sdk/env/step", {
+            "session_id": self.session_id,
+            "action": action,
+        })
+        observation = payload["observation"]
+        return (
+            {"screenshot": _decode_data_url_png(observation["screenshot"]), "goal": observation["goal"]},
+            float(payload["reward"]),
+            bool(payload["terminated"]),
+            bool(payload["truncated"]),
+            payload["info"],
+        )

appworld_sdk/errors.py

@@ -0,0 +1,38 @@
+"""App World SDK exception hierarchy."""
+
+from __future__ import annotations
+
+
+class AppWorldError(Exception):
+    """Base exception for all App World SDK errors."""
+
+
+class AppWorldAPIError(AppWorldError):
+    """Error returned by the App World API server."""
+
+    def __init__(self, message: str, *, status_code: int = 0, detail: str = ""):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"[{status_code}] {message}" if status_code else message)
+
+
+class EnvironmentNotReady(AppWorldAPIError):
+    """The requested environment is not available (no live backend)."""
+
+    def __init__(self, env_or_session_id: str, *, detail: str = ""):
+        super().__init__(
+            f"Environment or session '{env_or_session_id}' is not ready",
+            status_code=503,
+            detail=detail,
+        )
+
+
+class SessionExpired(AppWorldAPIError):
+    """The SDK session has expired or been closed."""
+
+    def __init__(self, session_id: str, *, detail: str = ""):
+        super().__init__(
+            f"Session '{session_id}' has expired or been closed",
+            status_code=410,
+            detail=detail,
+        )

appworld_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: appworld-sdk
+Version: 0.1.0
+Summary: Client SDK for App World — RL & Eval environments for Android apps
+Author: App World Contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/anthropics/app-world
+Project-URL: Documentation, https://github.com/anthropics/app-world#readme
+Project-URL: Repository, https://github.com/anthropics/app-world
+Project-URL: Issues, https://github.com/anthropics/app-world/issues
+Keywords: android,reinforcement-learning,gymnasium,evaluation,mobile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0,>=2.28
+Requires-Dist: numpy<3.0,>=1.24
+Requires-Dist: Pillow<12.0,>=9.0
+Requires-Dist: gymnasium<2.0,>=0.29
+Dynamic: license-file
+
+# App World SDK
+
+Lightweight Python client for the **App World** platform — RL training and evaluation on real Android apps, with a standard [Gymnasium](https://gymnasium.farama.org/) interface.
+
+## Installation
+
+```bash
+pip install appworld-sdk
+```
+
+**Requirements:** Python >= 3.11
+
+## Quick Start
+
+```python
+from appworld_sdk import AppWorldClient
+
+client = AppWorldClient(api_key="YOUR_API_KEY", base_url="https://api.appworld.dev")
+
+# Browse available tasks
+tasks = client.list_tasks()
+
+# Allocate device resources
+env_info = client.create_environment(task_ids=["FennoteCreateNote"])
+env_id = env_info["id"]
+
+# Get a Gymnasium-compatible environment
+env = client.make_env(env_id=env_id, env_type="eval")
+
+# Run a task
+obs, info = env.reset(task_name="FennoteCreateNote")
+done = False
+while not done:
+    action = {"action_type": 0, "x": 0.5, "y": 0.5, "text": "", "direction": 0}
+    obs, reward, terminated, truncated, info = env.step(action)
+    done = terminated or truncated
+
+env.close()
+```
+
+## Environment Types
+
+| Type | Class | Actions | Use Case |
+|------|-------|---------|----------|
+| `"rl"` | `RemoteAppWorldEnv` | 5 discrete (tap, swipe, etc.) | RL training |
+| `"eval"` | `RemoteAppWorldEvalEnv` | 7 (incl. text input) | Agent evaluation |
+
+## Client-Side Eval with Custom Agents
+
+Implement the `BaseAgent` protocol to run evaluations where LLM calls stay on your side — your model API key never leaves the local process.
+
+```python
+from appworld_sdk import AppWorldClient, BaseAgent
+
+class MyAgent:
+    def predict(self, *, screenshot, goal, **kwargs) -> dict:
+        # Your model inference here
+        return {"action_type": 0, "x": 0.5, "y": 0.5, "text": "", "direction": 0}
+
+client = AppWorldClient(api_key="YOUR_API_KEY")
+env_info = client.create_environment(task_ids=["FennoteCreateNote", "FennoteDeleteNote"])
+
+result = client.run_local_eval(
+    env_id=env_info["id"],
+    tasks=["FennoteCreateNote", "FennoteDeleteNote"],
+    agent=MyAgent(),
+    max_steps=15,
+)
+
+print(f"Success rate: {result.success_rate:.0%}")
+print(f"Avg steps: {result.avg_steps:.1f}")
+```
+
+## Server-Side Eval
+
+Let the platform handle LLM calls:
+
+```python
+result = client.run_eval(
+    env_id=env_info["id"],
+    tasks=["FennoteCreateNote"],
+    model_provider="anthropic",
+    model_api_key="YOUR_MODEL_KEY",
+    model_name="claude-sonnet-4-20250514",
+)
+print(f"Success rate: {result.success_rate}")
+```
+
+## API Reference
+
+### `AppWorldClient(api_key, base_url, timeout)`
+
+| Method | Description |
+|--------|-------------|
+| `list_apps(**filters)` | List available apps |
+| `list_tasks(**filters)` | List available tasks |
+| `get_task(task_id)` | Get task details |
+| `create_environment(task_ids, name)` | Allocate device resources |
+| `delete_environment(env_id)` | Release resources |
+| `make_env(env_id, env_type)` | Create Gymnasium env |
+| `run_eval(...)` | Server-side evaluation |
+| `run_local_eval(...)` | Client-side evaluation |
+
+### Exceptions
+
+| Exception | HTTP | Meaning |
+|-----------|------|---------|
+| `AppWorldError` | — | Base exception |
+| `AppWorldAPIError` | any | Server returned an error |
+| `EnvironmentNotReady` | 503 | Device not available |
+| `SessionExpired` | 410 | Session closed or timed out |
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

appworld_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+appworld_sdk/__init__.py,sha256=SrlajubHTsiAMMysvnZ8efdjTwE44PCZ7D9qM8apwec,821
+appworld_sdk/agent.py,sha256=sVmZPKQWuCJYIqIDapsBjTj1PTxoQmNVQhhZ97CBV2M,1112
+appworld_sdk/client.py,sha256=Cano9MPj6CR4RiyOAEynPvZJLJCioXqCjkEqTqfMbRY,17430
+appworld_sdk/env.py,sha256=RaxIzK_IyI9T6s1xV1Ix5_Il-bbuHgawZopDF2alYdY,6468
+appworld_sdk/errors.py,sha256=V2MK80-Vfcm2kOt73sRF_WcCdyeim9f5EmEY-Pf_Ruc,1166
+appworld_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+appworld_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=GsyI097vvTujs35rsA9mDo_8Z13esTTJ8LLFSH6YHI0,10774
+appworld_sdk-0.1.0.dist-info/METADATA,sha256=AUAPTCaX-7vIPmo3bKporUd35Bif-p0KNDcPieiYY1I,4394
+appworld_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+appworld_sdk-0.1.0.dist-info/top_level.txt,sha256=z43Vxbs5luZ2oCEzCEZsY1f2MIfOwU6P8UYTf7asK8c,13
+appworld_sdk-0.1.0.dist-info/RECORD,,

appworld_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

appworld_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 App World Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

appworld_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+appworld_sdk