clousd 0.1.0__tar.gz

clousd-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: clousd
+Version: 0.1.0
+Summary: Cloud Android phones modelled on real devices: API client for scripts and AI agents
+License: MIT
+Project-URL: Homepage, https://clousd.com/agents/
+Project-URL: Documentation, https://clousd.com/docs/
+Keywords: android,cloud phone,ai agents,mobile automation,testing
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# clousd
+
+Python client for [CLOUSD](https://clousd.com/agents/): cloud Android phones modelled on real devices, for scripts
+and AI agents. Look at the screen, act on it, reset the phone to a saved state between runs, clone as many copies as
+the job needs.
+
+Early access: ask for a key at [clousd.com/agents](https://clousd.com/agents/#access).
+
+```bash
+pip install "git+https://github.com/Clousd-Android/clousd-sdk#subdirectory=python"
+export CLOUSD_API_KEY=cl_live_...
+```
+
+## One run
+
+```python
+from clousd import Clousd
+
+c = Clousd()                                   # key from CLOUSD_API_KEY
+phone = c.device("dev_04f2")
+
+snap = next(s for s in phone.snapshots() if s["restorable"])
+phone.restore(snap["id"])                      # reset: every run starts from the same state
+
+png = phone.screenshot(width=540)              # look (JPEG when width is given, PNG otherwise)
+print(phone.screen_text())                     # every text on the screen
+
+phone.open_app("com.android.chrome")           # act
+phone.tap_text("Search")
+phone.type("weather in Berlin")
+phone.key("enter")
+
+phone.wait_text("Berlin", timeout=30)          # check
+```
+
+## What a device can do
+
+| Look | Act | State |
+|---|---|---|
+| `screenshot(width=None)` | `tap(x, y)`, `swipe(x, y, x2, y2, ms)`, `scroll("down")` | `snapshots()` |
+| `screen_text()` | `type(text)`, `key("back")` | `save_snapshot()` |
+| `find_text(text)` | `open_app(pkg)`, `close_app(pkg)`, `open_url(url)` | `restore(id)` |
+| `size()` | `tap_text(text)`, `wait_text(text, timeout)` | `clone(id, name)` |
+| `installed()`, `logs()` | `start()`, `stop()`, `restart()` | `c.job(id).wait()` |
+
+Coordinates are device pixels (`size()` gives the screen). Long operations return a `Job`; they wait by default,
+pass `wait=False` to poll yourself. Errors raise `ClousdError` with the HTTP status, a short code and a message.
+The API allows 60 requests a minute per key; the client waits and retries on 429.
+
+For checks from inside the phone (app databases, files, `dumpsys`) open an ADB session to the device from the
+dashboard or `POST /v1/devices/{name}/adb`.
+
+## Plug a phone into an AI agent
+
+[`clousd-mcp`](../mcp) exposes the same operations as MCP tools for any MCP-capable agent.
+
+MIT license.

clousd-0.1.0/README.md

@@ -0,0 +1,57 @@
+# clousd
+
+Python client for [CLOUSD](https://clousd.com/agents/): cloud Android phones modelled on real devices, for scripts
+and AI agents. Look at the screen, act on it, reset the phone to a saved state between runs, clone as many copies as
+the job needs.
+
+Early access: ask for a key at [clousd.com/agents](https://clousd.com/agents/#access).
+
+```bash
+pip install "git+https://github.com/Clousd-Android/clousd-sdk#subdirectory=python"
+export CLOUSD_API_KEY=cl_live_...
+```
+
+## One run
+
+```python
+from clousd import Clousd
+
+c = Clousd()                                   # key from CLOUSD_API_KEY
+phone = c.device("dev_04f2")
+
+snap = next(s for s in phone.snapshots() if s["restorable"])
+phone.restore(snap["id"])                      # reset: every run starts from the same state
+
+png = phone.screenshot(width=540)              # look (JPEG when width is given, PNG otherwise)
+print(phone.screen_text())                     # every text on the screen
+
+phone.open_app("com.android.chrome")           # act
+phone.tap_text("Search")
+phone.type("weather in Berlin")
+phone.key("enter")
+
+phone.wait_text("Berlin", timeout=30)          # check
+```
+
+## What a device can do
+
+| Look | Act | State |
+|---|---|---|
+| `screenshot(width=None)` | `tap(x, y)`, `swipe(x, y, x2, y2, ms)`, `scroll("down")` | `snapshots()` |
+| `screen_text()` | `type(text)`, `key("back")` | `save_snapshot()` |
+| `find_text(text)` | `open_app(pkg)`, `close_app(pkg)`, `open_url(url)` | `restore(id)` |
+| `size()` | `tap_text(text)`, `wait_text(text, timeout)` | `clone(id, name)` |
+| `installed()`, `logs()` | `start()`, `stop()`, `restart()` | `c.job(id).wait()` |
+
+Coordinates are device pixels (`size()` gives the screen). Long operations return a `Job`; they wait by default,
+pass `wait=False` to poll yourself. Errors raise `ClousdError` with the HTTP status, a short code and a message.
+The API allows 60 requests a minute per key; the client waits and retries on 429.
+
+For checks from inside the phone (app databases, files, `dumpsys`) open an ADB session to the device from the
+dashboard or `POST /v1/devices/{name}/adb`.
+
+## Plug a phone into an AI agent
+
+[`clousd-mcp`](../mcp) exposes the same operations as MCP tools for any MCP-capable agent.
+
+MIT license.

clousd-0.1.0/clousd/__init__.py

@@ -0,0 +1,5 @@
+"""CLOUSD: cloud Android phones modelled on real devices, for people, scripts and AI agents."""
+from .client import Clousd, ClousdError, Device, Job
+
+__all__ = ["Clousd", "ClousdError", "Device", "Job"]
+__version__ = "0.1.0"

clousd-0.1.0/clousd/client.py

@@ -0,0 +1,334 @@
+"""CLOUSD API v1 client: cloud Android phones for people, scripts and AI agents.
+
+    from clousd import Clousd
+    c = Clousd()                          # CLOUSD_API_KEY from the environment
+    phone = c.device("dev_04f2")
+    phone.restore("v3", wait=True)        # reset to a saved state
+    png = phone.screenshot()              # look
+    phone.tap_text("Add to cart")         # act
+    phone.wait_text("Added")              # check
+
+Every call is a plain HTTPS request to https://api.clousd.com/v1 with `Authorization: Bearer cl_live_…`.
+Long operations (start, snapshots, restore, clone) return a Job; `wait=True` or `job.wait()` polls it.
+"""
+from __future__ import annotations
+
+import base64
+import os
+import struct
+import time
+from typing import Any, Dict, List, Optional
+
+import requests
+
+DEFAULT_URL = "https://api.clousd.com/v1"
+
+
+class ClousdError(Exception):
+    """An API error: HTTP status, the short error code and the human message from the server."""
+
+    def __init__(self, status: int, error: str, message: str = ""):
+        super().__init__(f"{status} {error}: {message}" if message else f"{status} {error}")
+        self.status, self.error, self.message = status, error, message
+
+
+class Clousd:
+    """Account-level client. `api_key` defaults to $CLOUSD_API_KEY, `base_url` to $CLOUSD_API_URL."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 60.0):
+        self.api_key = api_key or os.environ.get("CLOUSD_API_KEY", "")
+        if not self.api_key:
+            raise ValueError("no API key: pass api_key= or set CLOUSD_API_KEY (Settings → API keys in the dashboard)")
+        self.base_url = (base_url or os.environ.get("CLOUSD_API_URL") or DEFAULT_URL).rstrip("/")
+        self.timeout = timeout
+        self._http = requests.Session()
+        self._http.headers.update({"Authorization": "Bearer " + self.api_key, "User-Agent": "clousd-python/0.1"})
+
+    # -- transport ---------------------------------------------------------------------------------------------
+    def request(self, method: str, path: str, json: Any = None, params: Any = None,
+                timeout: Optional[float] = None, raw: bool = False) -> Any:
+        """One API call. Retries politely on 429 (60 requests a minute per key) and on a dropped connection."""
+        url = self.base_url + "/" + path.lstrip("/")
+        for attempt in range(5):
+            try:
+                r = self._http.request(method, url, json=json, params=params, timeout=timeout or self.timeout)
+            except requests.ConnectionError:
+                if attempt == 4:
+                    raise
+                time.sleep(1 + attempt)
+                continue
+            if r.status_code == 429 and attempt < 4:
+                ra = r.headers.get("Retry-After")
+                time.sleep(float(ra) if ra and ra.replace(".", "", 1).isdigit() else min(2 ** (attempt + 1), 30))
+                continue
+            if r.status_code >= 400:
+                try:
+                    body = r.json()
+                    raise ClousdError(r.status_code, str(body.get("error", "error")), str(body.get("message", "")))
+                except ValueError:
+                    raise ClousdError(r.status_code, "error", r.text.strip()[:300]) from None
+            if raw:
+                return r.content
+            return r.json() if r.content else {}
+        raise ClousdError(429, "rate_limited", "too many requests")
+
+    def __repr__(self) -> str:   # never shows the key
+        return f"<Clousd {self.base_url}>"
+
+    # -- account -----------------------------------------------------------------------------------------------
+    def devices(self) -> List["Device"]:
+        """Devices this key can see."""
+        return [Device(self, d["name"], d) for d in self.request("GET", "devices").get("devices", [])]
+
+    def device(self, name: str) -> "Device":
+        """A handle to one device (no request is made until you use it)."""
+        return Device(self, name)
+
+    def create_device(self, profile: str, network: Optional[Dict[str, Any]] = None, plan: str = "metered",
+                      idempotency_key: Optional[str] = None, region: Optional[str] = None, burner: bool = False,
+                      wait: bool = True, timeout: float = 600) -> "Device":
+        """Create one device on this account (charged like the dashboard: creation fee, first month for plan monthly,
+        paid exits metered per GB). `profile` from models(); `network` like {"type": "residential", "country": "US"} or
+        {"type": "byo", "url": "socks5://…"}; `idempotency_key` - a retry with the same key within 10 minutes is not
+        charged twice (one is generated if not given). With wait=True returns once the device is running."""
+        import uuid
+        body: Dict[str, Any] = {"profile": profile, "network": network or {"type": "off"}, "plan": plan, "burner": burner,
+                                "idempotency_key": idempotency_key or uuid.uuid4().hex}
+        if region:
+            body["region"] = region
+        r = self.request("POST", "devices", json=body, timeout=90)
+        d = Device(self, r["name"], {"name": r["name"], "state": r.get("state", "starting")})
+        if wait:
+            end = time.time() + timeout
+            while d.refresh().get("state") in ("starting", "") and time.time() < end:
+                time.sleep(5)
+        return d
+
+    def job(self, job_id: str) -> "Job":
+        return Job(self, self.request("GET", f"jobs/{job_id}").get("job", {"id": job_id}))
+
+    def usage(self) -> Dict[str, Any]:
+        return self.request("GET", "usage")
+
+    def network_options(self) -> Dict[str, Any]:
+        """What can be chosen when creating a device right now: {types, countries:[{code,name}], plans}."""
+        return self.request("GET", "network/options")
+
+    def models(self) -> List[Dict[str, Any]]:
+        """Phone models available to create devices from."""
+        return self.request("GET", "models").get("models", [])
+
+    def _job(self, resp: Dict[str, Any], wait: bool, timeout: float) -> "Job":
+        job = Job(self, resp.get("job") or {"state": "done", "output": resp.get("output", "")})
+        return job.wait(timeout) if wait else job
+
+
+class Job:
+    """A long operation. `state` is running, done or failed."""
+
+    def __init__(self, client: Clousd, data: Dict[str, Any]):
+        self.client, self.data = client, data
+
+    id = property(lambda self: self.data.get("id", ""))
+    state = property(lambda self: self.data.get("state", ""))
+    output = property(lambda self: self.data.get("output", ""))
+
+    def refresh(self) -> "Job":
+        if self.id:
+            self.data = self.client.request("GET", f"jobs/{self.id}").get("job", self.data)
+        return self
+
+    def wait(self, timeout: float = 900, every: float = 3.0) -> "Job":
+        """Poll until the job finishes; raises ClousdError if it failed or ran out of time."""
+        end = time.time() + timeout
+        while self.state == "running" and self.id:
+            if time.time() > end:
+                raise ClousdError(408, "timeout", f"job {self.id} still running after {int(timeout)} s")
+            time.sleep(every)
+            self.refresh()
+        if self.state == "failed":
+            raise ClousdError(500, "job_failed", self.output.strip()[-500:])
+        return self
+
+    def __repr__(self) -> str:
+        return f"<Job {self.id} {self.state}>"
+
+
+class Device:
+    """One cloud phone. Coordinates are device pixels (see `size()`)."""
+
+    def __init__(self, client: Clousd, name: str, data: Optional[Dict[str, Any]] = None):
+        self.client, self.name, self.data = client, name, data or {}
+        self._size: Optional[tuple] = None
+
+    def _p(self, sub: str = "") -> str:
+        return f"devices/{self.name}" + ("/" + sub if sub else "")
+
+    # -- state -------------------------------------------------------------------------------------------------
+    def refresh(self) -> Dict[str, Any]:
+        self.data = self.client.request("GET", self._p()).get("device", {})
+        return self.data
+
+    @property
+    def state(self) -> str:
+        return (self.data or self.refresh()).get("state", "")
+
+    def start(self, wait: bool = True, timeout: float = 900) -> Job:
+        return self.client._job(self.client.request("POST", self._p("start")), wait, timeout)
+
+    def stop(self, wait: bool = True, timeout: float = 300) -> Job:
+        return self.client._job(self.client.request("POST", self._p("stop")), wait, timeout)
+
+    def restart(self, wait: bool = True, timeout: float = 900) -> Job:
+        return self.client._job(self.client.request("POST", self._p("restart")), wait, timeout)
+
+    def logs(self) -> Any:
+        """Recent logcat lines."""
+        return self.client.request("GET", self._p("logs"))
+
+    # -- look --------------------------------------------------------------------------------------------------
+    def screenshot(self, width: Optional[int] = None) -> bytes:
+        """The screen as PNG (full size) or, with `width`, a smaller JPEG."""
+        return self.client.request("GET", self._p("screenshot"), params={"w": width} if width else None, raw=True)
+
+    def size(self) -> tuple:
+        """Screen size in device pixels, read from a full-size screenshot once."""
+        if not self._size:
+            png = self.screenshot()
+            if png[:8] == b"\x89PNG\r\n\x1a\n":
+                self._size = struct.unpack(">II", png[16:24])
+            else:
+                self._size = (1080, 2400)
+        return self._size
+
+    def observe(self, width: int = 540, ui: bool = True) -> Dict[str, Any]:
+        """One fresh look at the phone: {seq, screen:{w,h}, image:{w,h,format,data}, image_bytes, package, activity,
+        ui:[{text, desc, id, class, b:[x1,y1,x2,y2], click, scroll, focused, ...}], ui_error}.
+        Coordinates in `ui` are phone pixels. `width` is a maximum: the image is shrunk by a whole factor, its real
+        width is image.w (scale to the phone = screen.w / image.w). Pass `seq` to act() so an action on a screen that
+        has changed since is refused (409 stale) instead of landing in the wrong place."""
+        d = self.client.request("GET", self._p("observe"), params={"w": width, "ui": 1 if ui else 0}, timeout=90)
+        d["image_bytes"] = base64.b64decode(d.get("image", {}).get("data", "") or b"")
+        if d.get("screen"):
+            self._size = (d["screen"]["w"], d["screen"]["h"])
+        return d
+
+    def act(self, op: str, settle: bool = True, seq: Optional[int] = None, **kw: Any) -> Dict[str, Any]:
+        """Do one action (same ops as `action`) and, with settle, wait until the screen stops changing (up to 5 s).
+        Returns {ok, output, seq, settled, changed, waited_ms}: changed=False means the screen did not change at all
+        (the action probably missed). With `seq` from observe() raises ClousdError 409 "stale" and does nothing if the
+        screen changed since (another observe or act happened)."""
+        body = {"op": op, "settle": settle, **kw}
+        if seq:
+            body["seq"] = seq
+        return self.client.request("POST", self._p("act"), json=body, timeout=(kw.get("ms", 0) / 1000 + 90))
+
+    def screen_text(self) -> List[str]:
+        """All texts on the screen (buttons, labels, fields) from the UI hierarchy."""
+        return self.action("screen_text").get("texts", [])
+
+    def find_text(self, text: str) -> str:
+        """Where `text` is on the screen ("found … at x,y"); raises if it is not there."""
+        return self.action("find_text", text=text).get("output", "")
+
+    def installed(self) -> List[str]:
+        return self.action("installed").get("packages", [])
+
+    # -- act ---------------------------------------------------------------------------------------------------
+    def action(self, op: str, timeout: Optional[float] = None, **kw: Any) -> Dict[str, Any]:
+        """Low-level: POST /devices/{name}/action {op, …}."""
+        return self.client.request("POST", self._p("action"), json={"op": op, **kw}, timeout=timeout)
+
+    def tap(self, x: int, y: int) -> str:
+        return self.action("tap", x=int(x), y=int(y)).get("output", "")
+
+    def tap_norm(self, x: float, y: float) -> str:
+        """Tap at a point given as fractions of the screen (0..1), independent of the screenshot size."""
+        w, h = self.size()
+        return self.tap(round(x * (w - 1)), round(y * (h - 1)))
+
+    def swipe(self, x: int, y: int, x2: int, y2: int, ms: int = 300) -> str:
+        return self.action("swipe", x=int(x), y=int(y), x2=int(x2), y2=int(y2), ms=int(ms)).get("output", "")
+
+    def scroll(self, direction: str = "down") -> str:
+        """One human-like swipe through a feed: down or up."""
+        return self.action("scroll", text=direction).get("output", "")
+
+    def type(self, text: str) -> str:
+        """Type into the focused field, any language: ASCII goes through the keyboard, everything else is pasted from
+        the phone's clipboard by the agent (the clipboard is cleared afterwards). One line, no control characters."""
+        if "\n" in text or "\r" in text or "\x00" in text:
+            raise ValueError("type(): one line, no control characters")
+        return self.action("text", text=text).get("output", "")
+
+    def key(self, key: str) -> str:
+        """home, back, recents, enter, power, tab, del, menu, volume_up, volume_down, wake, sleep or a keycode."""
+        return self.action("key", key=str(key)).get("output", "")
+
+    def open_app(self, package: str) -> str:
+        return self.action("open_app", package=package).get("output", "")
+
+    def close_app(self, package: str) -> str:
+        return self.action("close_app", package=package).get("output", "")
+
+    def open_url(self, url: str) -> str:
+        return self.action("url", url=url).get("output", "")
+
+    def tap_text(self, text: str) -> str:
+        """Tap the first element whose text contains `text` (case-insensitive)."""
+        return self.action("tap_text", text=text).get("output", "")
+
+    def wait_text(self, text: str, timeout: int = 30) -> str:
+        """Wait until `text` appears on the screen (up to 120 s); raises if it does not."""
+        t = max(1, min(int(timeout), 120))
+        return self.action("wait_text", text=text, ms=t * 1000, timeout=t + 60).get("output", "")
+
+    # -- core primitives (same ops and result shapes as the Lusiesta core protocol) --------------------------------
+    def op(self, op: str, timeout: Optional[float] = None, **args: Any) -> Dict[str, Any]:
+        """One primitive: shell {argv, timeout} → {rc, out_b64, err_b64}; dump → {xml_z}; launch_app {package,
+        activity}, start_activity {component}, force_stop {package} → {rc}; foreground → {package}; screenshot →
+        {png_b64}; screen → {w, h}; tap {x, y}, long_press {x, y, ms}, swipe {x1, y1, x2, y2, ms}, key {code, meta},
+        text {value}, clear_field → {}; ip_check → {ok, ip, country, …}. shell needs ADB access enabled for the device
+        (adb_enable) and your IP in its allow list - the same gate as adb shell."""
+        r = self.client.request("POST", self._p("op"), json={"op": op, "args": args}, timeout=timeout)
+        return r.get("data", {})
+
+    def shell(self, *argv: str, timeout: float = 30) -> tuple:
+        """Run a command on the phone as the shell user (like `adb shell`): returns (rc, stdout, stderr) as str."""
+        d = self.client.request("POST", self._p("op"), json={"op": "shell", "args": {"argv": list(argv), "timeout": timeout}},
+                                timeout=timeout + 30).get("data", {})
+        dec = lambda k: base64.b64decode(d.get(k, "") or b"").decode("utf-8", "replace")
+        return d.get("rc", -1), dec("out_b64"), dec("err_b64")
+
+    def push(self, data: bytes, remote: str, timeout: float = 900) -> Dict[str, Any]:
+        """Put a file on the phone under /sdcard/ or /data/local/tmp/ (like `adb push`; same gate as shell)."""
+        url = self.client.base_url + "/" + self._p("files")
+        r = self.client._http.put(url, params={"path": remote}, data=data, timeout=timeout)
+        if r.status_code >= 400:
+            body = r.json() if r.content else {}
+            raise ClousdError(r.status_code, str(body.get("error", "error")), str(body.get("message", "")))
+        return r.json().get("data", {})
+
+    def adb_enable(self, allow_ips: List[str], ttl_hours: int = 24) -> Dict[str, Any]:
+        """Enable ADB access to the device for these IPs/CIDRs (also unlocks shell/push); returns host, port, code."""
+        return self.client.request("POST", self._p("adb"), json={"ttl_hours": ttl_hours, "allow_ips": allow_ips})
+
+    # -- state between runs ------------------------------------------------------------------------------------
+    def snapshots(self) -> List[Dict[str, Any]]:
+        """Saved states of this device: id, created, android, current, restorable."""
+        return self.client.request("GET", self._p("snapshots")).get("snapshots", [])
+
+    def save_snapshot(self, wait: bool = True, timeout: float = 1800) -> Job:
+        return self.client._job(self.client.request("POST", self._p("snapshots")), wait, timeout)
+
+    def restore(self, snapshot_id: str, wait: bool = True, timeout: float = 1800) -> Job:
+        """Reset the device to a saved state."""
+        return self.client._job(self.client.request("POST", self._p(f"snapshots/{snapshot_id}/restore")), wait, timeout)
+
+    def clone(self, snapshot_id: str, name: str, wait: bool = True, timeout: float = 1800) -> "Device":
+        """A new device (`name`: letters and digits, up to 16) from a saved state of this one."""
+        self.client._job(self.client.request("POST", self._p(f"snapshots/{snapshot_id}/clone"), json={"name": name}), wait, timeout)
+        return Device(self.client, name)
+
+    def __repr__(self) -> str:
+        return f"<Device {self.name} {self.data.get('state', '')}>".replace(" >", ">")

clousd-0.1.0/clousd.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: clousd
+Version: 0.1.0
+Summary: Cloud Android phones modelled on real devices: API client for scripts and AI agents
+License: MIT
+Project-URL: Homepage, https://clousd.com/agents/
+Project-URL: Documentation, https://clousd.com/docs/
+Keywords: android,cloud phone,ai agents,mobile automation,testing
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# clousd
+
+Python client for [CLOUSD](https://clousd.com/agents/): cloud Android phones modelled on real devices, for scripts
+and AI agents. Look at the screen, act on it, reset the phone to a saved state between runs, clone as many copies as
+the job needs.
+
+Early access: ask for a key at [clousd.com/agents](https://clousd.com/agents/#access).
+
+```bash
+pip install "git+https://github.com/Clousd-Android/clousd-sdk#subdirectory=python"
+export CLOUSD_API_KEY=cl_live_...
+```
+
+## One run
+
+```python
+from clousd import Clousd
+
+c = Clousd()                                   # key from CLOUSD_API_KEY
+phone = c.device("dev_04f2")
+
+snap = next(s for s in phone.snapshots() if s["restorable"])
+phone.restore(snap["id"])                      # reset: every run starts from the same state
+
+png = phone.screenshot(width=540)              # look (JPEG when width is given, PNG otherwise)
+print(phone.screen_text())                     # every text on the screen
+
+phone.open_app("com.android.chrome")           # act
+phone.tap_text("Search")
+phone.type("weather in Berlin")
+phone.key("enter")
+
+phone.wait_text("Berlin", timeout=30)          # check
+```
+
+## What a device can do
+
+| Look | Act | State |
+|---|---|---|
+| `screenshot(width=None)` | `tap(x, y)`, `swipe(x, y, x2, y2, ms)`, `scroll("down")` | `snapshots()` |
+| `screen_text()` | `type(text)`, `key("back")` | `save_snapshot()` |
+| `find_text(text)` | `open_app(pkg)`, `close_app(pkg)`, `open_url(url)` | `restore(id)` |
+| `size()` | `tap_text(text)`, `wait_text(text, timeout)` | `clone(id, name)` |
+| `installed()`, `logs()` | `start()`, `stop()`, `restart()` | `c.job(id).wait()` |
+
+Coordinates are device pixels (`size()` gives the screen). Long operations return a `Job`; they wait by default,
+pass `wait=False` to poll yourself. Errors raise `ClousdError` with the HTTP status, a short code and a message.
+The API allows 60 requests a minute per key; the client waits and retries on 429.
+
+For checks from inside the phone (app databases, files, `dumpsys`) open an ADB session to the device from the
+dashboard or `POST /v1/devices/{name}/adb`.
+
+## Plug a phone into an AI agent
+
+[`clousd-mcp`](../mcp) exposes the same operations as MCP tools for any MCP-capable agent.
+
+MIT license.

clousd-0.1.0/clousd.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+clousd/__init__.py
+clousd/client.py
+clousd.egg-info/PKG-INFO
+clousd.egg-info/SOURCES.txt
+clousd.egg-info/dependency_links.txt
+clousd.egg-info/requires.txt
+clousd.egg-info/top_level.txt
+tests/test_client.py

clousd-0.1.0/clousd.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clousd-0.1.0/clousd.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

clousd-0.1.0/clousd.egg-info/top_level.txt

@@ -0,0 +1 @@
+clousd

clousd-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "clousd"
+version = "0.1.0"
+description = "Cloud Android phones modelled on real devices: API client for scripts and AI agents"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = ["requests>=2.28"]
+keywords = ["android", "cloud phone", "ai agents", "mobile automation", "testing"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://clousd.com/agents/"
+Documentation = "https://clousd.com/docs/"
+
+[tool.setuptools]
+packages = ["clousd"]

clousd-0.1.0/setup.cfg

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

clousd-0.1.0/tests/test_client.py

@@ -0,0 +1,149 @@
+"""Offline tests of the clousd client against a tiny fake /v1 server (no real phones are touched).
+
+    python -m unittest discover -s sdk/python/tests
+"""
+import json
+import os
+import struct
+import sys
+import threading
+import unittest
+import zlib
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from clousd import Clousd, ClousdError  # noqa: E402
+
+
+def tiny_png(w, h):
+    raw = b"".join(b"\x00" + b"\x00\x00\x00" * w for _ in range(h))
+    chunk = lambda t, d: struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d) & 0xFFFFFFFF)
+    return b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0)) + \
+        chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b"")
+
+
+class Fake(BaseHTTPRequestHandler):
+    calls = []
+    job_polls = 0
+    rate_limited_once = False
+
+    def log_message(self, *a):
+        pass
+
+    def _send(self, code, obj=None, raw=None, ctype="application/json", headers=None):
+        body = raw if raw is not None else json.dumps(obj).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _record(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        body = json.loads(self.rfile.read(n) or b"{}") if n else None
+        Fake.calls.append((self.command, self.path, body, self.headers.get("Authorization")))
+        return body
+
+    def do_GET(self):
+        self._record()
+        p = self.path
+        if p == "/v1/devices":
+            return self._send(200, {"devices": [{"name": "t1", "state": "running"}]})
+        if p.startswith("/v1/devices/t1/screenshot"):
+            return self._send(200, raw=tiny_png(1080, 2400), ctype="image/png")
+        if p == "/v1/devices/t1/snapshots":
+            return self._send(200, {"snapshots": [{"id": "v3", "restorable": True}]})
+        if p.startswith("/v1/devices/t1/observe"):
+            import base64
+            return self._send(200, {"seq": 7, "screen": {"w": 1080, "h": 2400},
+                                    "image": {"w": 540, "h": 1200, "format": "jpeg", "data": base64.b64encode(b"JPEGDATA").decode()},
+                                    "package": "com.android.settings", "activity": "com.android.settings.Settings",
+                                    "ui": [{"text": "Wi-Fi", "class": "TextView", "b": [0, 100, 540, 200], "click": True}]})
+        if p == "/v1/jobs/j1":
+            Fake.job_polls += 1
+            return self._send(200, {"job": {"id": "j1", "state": "done" if Fake.job_polls >= 2 else "running"}})
+        return self._send(404, {"error": "not_found", "message": "no such device"})
+
+    def do_POST(self):
+        body = self._record()
+        p = self.path
+        if p == "/v1/devices/t1/action":
+            if body["op"] == "screen_text" and not Fake.rate_limited_once:
+                Fake.rate_limited_once = True
+                return self._send(429, {"error": "rate_limited"}, headers={"Retry-After": "0"})
+            if body["op"] == "screen_text":
+                return self._send(200, {"ok": True, "texts": ["Settings", "Wi-Fi"]})
+            return self._send(200, {"ok": True, "output": "done " + body["op"]})
+        if p == "/v1/devices/t1/act":
+            return self._send(200, {"ok": True, "output": "", "seq": 7, "stale": body.get("seq", 7) != 7,
+                                    "settled": True, "waited_ms": 600})
+        if p == "/v1/devices/t1/snapshots/v3/restore":
+            return self._send(202, {"ok": True, "job": {"id": "j1", "state": "running"}})
+        return self._send(400, {"error": "bad_request", "message": "op"})
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.srv = HTTPServer(("127.0.0.1", 0), Fake)
+        threading.Thread(target=cls.srv.serve_forever, daemon=True).start()
+        cls.c = Clousd(api_key="cl_live_test", base_url=f"http://127.0.0.1:{cls.srv.server_port}/v1")
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.srv.shutdown()
+
+    def test_devices_and_auth(self):
+        ds = self.c.devices()
+        self.assertEqual([d.name for d in ds], ["t1"])
+        self.assertEqual(Fake.calls[-1][3], "Bearer cl_live_test")
+        self.assertNotIn("cl_live_test", repr(self.c))
+
+    def test_actions_shape(self):
+        d = self.c.device("t1")
+        d.tap(10, 20)
+        self.assertEqual(Fake.calls[-1][2], {"op": "tap", "x": 10, "y": 20})
+        d.wait_text("Done", timeout=500)
+        self.assertEqual(Fake.calls[-1][2], {"op": "wait_text", "text": "Done", "ms": 120000})
+        d.scroll("up")
+        self.assertEqual(Fake.calls[-1][2], {"op": "scroll", "text": "up"})
+        d.open_url("https://example.com")
+        self.assertEqual(Fake.calls[-1][2], {"op": "url", "url": "https://example.com"})
+
+    def test_screen_text_retries_429(self):
+        self.assertEqual(self.c.device("t1").screen_text(), ["Settings", "Wi-Fi"])
+
+    def test_size_from_png_and_tap_norm(self):
+        d = self.c.device("t1")
+        self.assertEqual(d.size(), (1080, 2400))
+        d.tap_norm(0.5, 0.5)
+        self.assertEqual(Fake.calls[-1][2], {"op": "tap", "x": 540, "y": 1200})
+
+    def test_restore_waits_for_job(self):
+        job = self.c.device("t1").restore("v3", timeout=30)
+        self.assertEqual(job.state, "done")
+
+    def test_observe_and_act(self):
+        d = self.c.device("t1")
+        o = d.observe()
+        self.assertEqual((o["seq"], o["image_bytes"], d.size()), (7, b"JPEGDATA", (1080, 2400)))
+        r = d.act("tap", x=270, y=150, seq=o["seq"])
+        self.assertEqual(Fake.calls[-1][2], {"op": "tap", "settle": True, "x": 270, "y": 150, "seq": 7})
+        self.assertEqual((r["settled"], r["stale"]), (True, False))
+
+    def test_type_any_language(self):
+        self.c.device("t1").type("こんにちは")
+        self.assertEqual(Fake.calls[-1][2], {"op": "text", "text": "こんにちは"})
+        with self.assertRaises(ValueError):
+            self.c.device("t1").type("two\nlines")
+
+    def test_errors_are_typed(self):
+        with self.assertRaises(ClousdError) as e:
+            self.c.device("nope").refresh()
+        self.assertEqual((e.exception.status, e.exception.error), (404, "not_found"))
+
+
+if __name__ == "__main__":
+    unittest.main()