cuakit 0.1.0__tar.gz

cuakit-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Node / web
+node_modules/
+.pnpm-store/
+.next/
+out/
+coverage/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.vscode/
+.idea/

cuakit-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: cuakit
+Version: 0.1.0
+Summary: Remote desktop control toolkit for cuakit workers
+Project-URL: Homepage, https://cuakit.bolte.cc
+Project-URL: Repository, https://github.com/bolte-dev/cuakit
+Author: cuakit maintainers
+License: MIT
+Keywords: agents,automation,desktop,pyautogui,remote
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: pydantic>=2.10.6
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.6; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Requires-Dist: ty>=0.0.1a14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cuakit Python SDK
+
+`cuakit` provides a pyautogui-like API for controlling remote cuakit workers.
+
+## Install
+
+```bash
+pip install cuakit
+```
+
+## Quick start
+
+```python
+from cuakit import CuakitClient
+
+client = CuakitClient(
+    base_url="https://cuakit.bolte.cc",
+    worker_id="cuaworker1",
+)
+
+client.wait_for_turn(timeout_s=90)
+client.move_to(500, 320)
+client.click(500, 320)
+client.typewrite("hello from cuakit")
+```
+
+## Queue behavior
+
+- `wait_for_turn()` joins queue and blocks until the lease is granted.
+- Each lease is one minute by default.
+- SDK and web users share the same queue.
+
+## Stream access
+
+```python
+stream = client.stream_info()
+print(stream.stream_url)
+```
+
+The stream URL can be opened in a browser/player to observe video and audio.
+
+## Publish to PyPI
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+This repository assumes `~/.pypirc` is already configured.

cuakit-0.1.0/README.md

@@ -0,0 +1,49 @@
+# cuakit Python SDK
+
+`cuakit` provides a pyautogui-like API for controlling remote cuakit workers.
+
+## Install
+
+```bash
+pip install cuakit
+```
+
+## Quick start
+
+```python
+from cuakit import CuakitClient
+
+client = CuakitClient(
+    base_url="https://cuakit.bolte.cc",
+    worker_id="cuaworker1",
+)
+
+client.wait_for_turn(timeout_s=90)
+client.move_to(500, 320)
+client.click(500, 320)
+client.typewrite("hello from cuakit")
+```
+
+## Queue behavior
+
+- `wait_for_turn()` joins queue and blocks until the lease is granted.
+- Each lease is one minute by default.
+- SDK and web users share the same queue.
+
+## Stream access
+
+```python
+stream = client.stream_info()
+print(stream.stream_url)
+```
+
+The stream URL can be opened in a browser/player to observe video and audio.
+
+## Publish to PyPI
+
+```bash
+python -m build
+twine upload dist/*
+```
+
+This repository assumes `~/.pypirc` is already configured.

cuakit-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cuakit"
+version = "0.1.0"
+description = "Remote desktop control toolkit for cuakit workers"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "cuakit maintainers" }]
+license = { text = "MIT" }
+keywords = ["automation", "desktop", "remote", "pyautogui", "agents"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent"
+]
+dependencies = [
+  "httpx>=0.27.2",
+  "pydantic>=2.10.6"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "pytest>=8.3.4",
+  "ruff>=0.9.6",
+  "ty>=0.0.1a14",
+  "twine>=6.1.0"
+]
+
+[project.urls]
+Homepage = "https://cuakit.bolte.cc"
+Repository = "https://github.com/bolte-dev/cuakit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cuakit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = []
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

cuakit-0.1.0/scripts/publish.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+python -m pip install --upgrade build twine
+python -m build
+twine upload dist/*

cuakit-0.1.0/src/cuakit/__init__.py

@@ -0,0 +1,10 @@
+from cuakit.client import CuakitClient
+from cuakit.errors import ApiError, CuakitError, QueueNotReadyError, QueueTimeoutError
+
+__all__ = [
+  "ApiError",
+  "CuakitClient",
+  "CuakitError",
+  "QueueNotReadyError",
+  "QueueTimeoutError",
+]

cuakit-0.1.0/src/cuakit/client.py

@@ -0,0 +1,176 @@
+import time
+import uuid
+from dataclasses import dataclass
+
+import httpx
+
+from cuakit.errors import ApiError, QueueNotReadyError, QueueTimeoutError
+from cuakit.types import CommandResult, QueueStatus, StreamInfo
+
+
+@dataclass(frozen=True)
+class _CommandEnvelope:
+  request_id: str
+  worker_id: str
+  command: dict[str, object]
+
+
+class CuakitClient:
+  """Remote desktop client with pyautogui-like methods.
+
+  Args:
+    base_url: cuakit control plane URL (for example https://cuakit.bolte.cc).
+    worker_id: Worker identifier to control.
+    client_id: Optional stable client id.
+    timeout_s: HTTP timeout per request.
+  """
+
+  def __init__(
+    self,
+    base_url: str,
+    worker_id: str = "cuaworker1",
+    client_id: str | None = None,
+    timeout_s: float = 15.0,
+  ) -> None:
+    self._base_url = base_url.rstrip("/")
+    self._worker_id = worker_id
+    self._client_id = client_id or str(uuid.uuid4())
+    self._http = httpx.Client(
+      timeout=timeout_s,
+      headers={"x-cuakit-client-id": self._client_id},
+    )
+
+  @property
+  def client_id(self) -> str:
+    return self._client_id
+
+  def close(self) -> None:
+    self._http.close()
+
+  def join_queue(self) -> QueueStatus:
+    payload = self._request_json("POST", "/api/queue/join")
+    return QueueStatus.model_validate(payload["status"])
+
+  def status(self) -> QueueStatus:
+    payload = self._request_json("GET", "/api/queue/status")
+    return QueueStatus.model_validate(payload["status"])
+
+  def release(self) -> QueueStatus:
+    payload = self._request_json("POST", "/api/queue/release")
+    return QueueStatus.model_validate(payload["status"])
+
+  def wait_for_turn(self, timeout_s: float = 120.0, poll_interval_s: float = 2.0) -> QueueStatus:
+    self.join_queue()
+    deadline = time.monotonic() + timeout_s
+
+    while True:
+      status = self.status()
+      if status.isController:
+        return status
+
+      if time.monotonic() >= deadline:
+        raise QueueTimeoutError(
+          f"Timed out waiting for controller lease for worker '{self._worker_id}'"
+        )
+
+      time.sleep(poll_interval_s)
+
+  def stream_info(self) -> StreamInfo:
+    payload = self._request_json("GET", "/api/control/stream")
+    mapped = {
+      "ok": payload["ok"],
+      "role": payload["role"],
+      "stream_url": payload["streamUrl"],
+      "status": payload["status"],
+    }
+    return StreamInfo.model_validate(mapped)
+
+  def move_to(self, x: int, y: int, duration_ms: int = 0) -> CommandResult:
+    return self._command({"type": "move_to", "x": x, "y": y, "duration_ms": duration_ms})
+
+  def moveTo(self, x: int, y: int, duration_ms: int = 0) -> CommandResult:  # noqa: N802
+    return self.move_to(x, y, duration_ms=duration_ms)
+
+  def click(self, x: int, y: int, button: str = "left") -> CommandResult:
+    return self._command({"type": "click", "x": x, "y": y, "button": button})
+
+  def double_click(self, x: int, y: int, button: str = "left") -> CommandResult:
+    return self._command({"type": "double_click", "x": x, "y": y, "button": button})
+
+  def mouse_down(self, x: int, y: int, button: str = "left") -> CommandResult:
+    return self._command({"type": "mouse_down", "x": x, "y": y, "button": button})
+
+  def mouse_up(self, x: int, y: int, button: str = "left") -> CommandResult:
+    return self._command({"type": "mouse_up", "x": x, "y": y, "button": button})
+
+  def scroll(self, clicks: int, x: int | None = None, y: int | None = None) -> CommandResult:
+    command: dict[str, object] = {"type": "scroll", "clicks": clicks}
+    if x is not None:
+      command["x"] = x
+    if y is not None:
+      command["y"] = y
+    return self._command(command)
+
+  def typewrite(self, text: str, interval_ms: int = 0) -> CommandResult:
+    return self._command({"type": "typewrite", "text": text, "interval_ms": interval_ms})
+
+  def write(self, text: str, interval_ms: int = 0) -> CommandResult:
+    return self.typewrite(text, interval_ms=interval_ms)
+
+  def press(self, key: str) -> CommandResult:
+    return self._command({"type": "press", "key": key})
+
+  def hotkey(self, *keys: str) -> CommandResult:
+    if not keys:
+      raise ValueError("hotkey requires at least one key")
+    return self._command({"type": "hotkey", "keys": list(keys)})
+
+  def sleep(self, duration_ms: int) -> CommandResult:
+    return self._command({"type": "sleep", "duration_ms": duration_ms})
+
+  def _command(self, command: dict[str, object]) -> CommandResult:
+    envelope = _CommandEnvelope(
+      request_id=str(uuid.uuid4()),
+      worker_id=self._worker_id,
+      command=command,
+    )
+    payload = self._request_json(
+      "POST",
+      "/api/control/command",
+      json={
+        "request_id": envelope.request_id,
+        "worker_id": envelope.worker_id,
+        "command": envelope.command,
+      },
+    )
+    return CommandResult.model_validate(payload)
+
+  def _request_json(
+    self,
+    method: str,
+    path: str,
+    json: dict[str, object] | None = None,
+  ) -> dict[str, object]:
+    response = self._http.request(method, f"{self._base_url}{path}", json=json)
+
+    try:
+      payload = response.json()
+    except ValueError as err:
+      raise ApiError(f"Invalid JSON response from {path}") from err
+
+    if response.status_code == 423:
+      raise QueueNotReadyError(payload.get("error", "Queue lease not active"))
+
+    if response.status_code >= 400:
+      raise ApiError(f"HTTP {response.status_code} from {path}: {payload}")
+
+    if not isinstance(payload, dict):
+      raise ApiError(f"Unexpected response payload from {path}")
+
+    return payload
+
+  def __enter__(self) -> "CuakitClient":
+    return self
+
+  def __exit__(self, exc_type, exc, tb) -> None:
+    self.close()

cuakit-0.1.0/src/cuakit/errors.py

@@ -0,0 +1,14 @@
+class CuakitError(Exception):
+  """Base SDK exception."""
+
+
+class QueueTimeoutError(CuakitError):
+  """Raised when waiting for queue control exceeds timeout."""
+
+
+class QueueNotReadyError(CuakitError):
+  """Raised when a control command is sent without controller lease."""
+
+
+class ApiError(CuakitError):
+  """Raised when the control plane returns an API error."""

cuakit-0.1.0/src/cuakit/types.py

@@ -0,0 +1,26 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class QueueStatus(BaseModel):
+  workerId: str
+  activeControllerId: str | None
+  expiresAt: int | None
+  queueLength: int
+  position: int | None
+  isController: bool
+
+
+class StreamInfo(BaseModel):
+  ok: bool
+  role: Literal["viewer", "controller"]
+  stream_url: str
+  status: QueueStatus
+
+
+class CommandResult(BaseModel):
+  ok: bool
+  request_id: str
+  worker_id: str
+  duration_ms: int

cuakit-0.1.0/tests/test_client.py

@@ -0,0 +1,73 @@
+import httpx
+import pytest
+
+from cuakit.client import CuakitClient
+from cuakit.errors import QueueNotReadyError
+
+
+def _build_client(
+  payloads: list[dict[str, object]],
+  statuses: list[int] | None = None,
+) -> CuakitClient:
+  statuses = statuses or [200] * len(payloads)
+  idx = {"value": 0}
+
+  def handler(request: httpx.Request) -> httpx.Response:
+    current = idx["value"]
+    idx["value"] += 1
+    return httpx.Response(statuses[current], json=payloads[current])
+
+  transport = httpx.MockTransport(handler)
+  client = CuakitClient("https://example.com")
+  client._http = httpx.Client(transport=transport)  # noqa: SLF001
+  return client
+
+
+def test_wait_for_turn_returns_controller() -> None:
+  client = _build_client(
+    payloads=[
+      {
+        "status": {
+          "workerId": "cuaworker1",
+          "activeControllerId": None,
+          "expiresAt": None,
+          "queueLength": 1,
+          "position": 1,
+          "isController": False,
+        }
+      },
+      {
+        "status": {
+          "workerId": "cuaworker1",
+          "activeControllerId": None,
+          "expiresAt": None,
+          "queueLength": 1,
+          "position": 1,
+          "isController": False,
+        }
+      },
+      {
+        "status": {
+          "workerId": "cuaworker1",
+          "activeControllerId": "abc",
+          "expiresAt": 12345,
+          "queueLength": 0,
+          "position": 0,
+          "isController": True,
+        }
+      },
+    ]
+  )
+
+  status = client.wait_for_turn(timeout_s=0.2, poll_interval_s=0.01)
+  assert status.isController is True
+
+
+def test_command_raises_when_not_controller() -> None:
+  client = _build_client(
+    payloads=[{"ok": False, "error": "Client does not hold active controller lease"}],
+    statuses=[423],
+  )
+
+  with pytest.raises(QueueNotReadyError):
+    client.click(10, 10)