qirabot 0.1.0__tar.gz

qirabot-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: qirabot
+Version: 0.1.0
+Summary: Official Python SDK for Qirabot - AI-powered device automation
+Author-email: Qirabot Team <support@qirabot.com>
+License-Expression: MIT
+Keywords: qirabot,automation,testing,ai,sdk,rpa
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"

qirabot-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qirabot"
+version = "0.1.0"
+description = "Official Python SDK for Qirabot - AI-powered device automation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Qirabot Team", email = "support@qirabot.com" }
+]
+keywords = ["qirabot", "automation", "testing", "ai", "sdk", "rpa"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "websockets>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

qirabot-0.1.0/setup.cfg

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

qirabot-0.1.0/src/qirabot/__init__.py

@@ -0,0 +1,31 @@
+"""Qirabot - AI-powered device automation SDK."""
+
+from qirabot.actions import Action
+from qirabot.client import DeviceInfo, Qirabot, TaskResult
+from qirabot.exceptions import (
+    ActionError,
+    AuthenticationError,
+    DeviceBusyError,
+    DeviceOfflineError,
+    LeaseExpiredError,
+    QirabotError,
+    QirabotTimeoutError,
+)
+from qirabot.task_context import ScreenshotEvent, StepEvent, TaskContext
+
+__all__ = [
+    "Action",
+    "ActionError",
+    "AuthenticationError",
+    "DeviceBusyError",
+    "DeviceInfo",
+    "DeviceOfflineError",
+    "LeaseExpiredError",
+    "Qirabot",
+    "QirabotError",
+    "QirabotTimeoutError",
+    "ScreenshotEvent",
+    "StepEvent",
+    "TaskContext",
+    "TaskResult",
+]

qirabot-0.1.0/src/qirabot/_transport.py

@@ -0,0 +1,172 @@
+"""HTTP + WebSocket transport layer for Qirabot SDK."""
+
+from __future__ import annotations
+
+import json
+import logging
+import struct
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+from urllib.parse import urlparse
+
+import httpx
+import websockets.sync.client as ws_sync
+
+from qirabot.exceptions import raise_for_error, QirabotTimeoutError
+
+logger = logging.getLogger("qirabot")
+
+
+@dataclass
+class StepMessage:
+    """A step event received from WebSocket."""
+
+    data: dict[str, Any]
+    screenshot: bytes | None = None
+
+
+class Transport:
+    """HTTP client with WebSocket support."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+    ):
+        self._base_url = base_url.rstrip("/")
+        self._api_url = f"{self._base_url}/api/v1"
+        self._api_key = api_key
+        self._headers = {"X-API-Key": api_key}
+        self._timeout = timeout
+        self._verify_ssl = verify_ssl
+        self._client = httpx.Client(
+            base_url=self._api_url,
+            headers=self._headers,
+            timeout=timeout,
+            verify=verify_ssl,
+        )
+
+    def request(self, method: str, path: str, json_data: dict[str, Any] | None = None) -> Any:
+        """Send an HTTP request and return parsed JSON response."""
+        response = self._client.request(method, path, json=json_data)
+        if response.status_code >= 400:
+            try:
+                data = response.json()
+            except Exception:
+                data = {"error": {"message": response.text or "Unknown error"}}
+            raise_for_error(response.status_code, data)
+        if response.status_code == 204:
+            return {}
+        try:
+            return response.json()
+        except Exception:
+            return {}
+
+    def post(self, path: str, json_data: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a POST request."""
+        return self.request("POST", path, json_data)
+
+    def delete(self, path: str) -> dict[str, Any]:
+        """Send a DELETE request."""
+        return self.request("DELETE", path)
+
+    def ws_connect(self, path: str, timeout: float | None = None) -> WSConnection:
+        """Open a WebSocket connection.
+
+        Args:
+            path: API path (e.g. "/sdk/tasks/{id}/ws").
+            timeout: Optional timeout override.
+
+        Returns:
+            A WSConnection wrapper.
+        """
+        connect_timeout = timeout or self._timeout
+        ws_url = self._build_ws_url(path)
+        additional_headers = {"X-API-Key": self._api_key}
+        conn = ws_sync.connect(
+            ws_url,
+            additional_headers=additional_headers,
+            open_timeout=connect_timeout,
+            close_timeout=10,
+            ping_interval=None,
+        )
+        return WSConnection(conn)
+
+    def get_bytes(self, path: str) -> bytes:
+        """Send a GET request and return raw bytes (for screenshot download)."""
+        response = self._client.get(path)
+        if response.status_code >= 400:
+            try:
+                data = response.json()
+            except Exception:
+                data = {"error": {"message": response.text or "Unknown error"}}
+            raise_for_error(response.status_code, data)
+        return response.content
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def _build_ws_url(self, path: str) -> str:
+        """Convert HTTP base URL to WebSocket URL."""
+        parsed = urlparse(self._api_url)
+        scheme = "wss" if parsed.scheme == "https" else "ws"
+        return f"{scheme}://{parsed.netloc}{parsed.path}{path}"
+
+
+class WSConnection:
+    """Wrapper around a WebSocket connection for SDK task action.
+
+    Server protocol:
+        - Text frame: JSON message (step event, result event, or error)
+        - Binary frame: composite [2-byte JSON length (big-endian)] [JSON] [PNG]
+          Used for step events with inline screenshots.
+    """
+
+    def __init__(self, conn: ws_sync.ClientConnection):
+        self._conn = conn
+
+    def send_action(self, action: dict[str, Any]) -> None:
+        """Send an execute_action request."""
+        msg = json.dumps({"type": "execute_action", "action": action})
+        self._conn.send(msg)
+
+    def receive(self, timeout: float | None = None) -> StepMessage:
+        """Receive the next message from the server.
+
+        Returns a StepMessage. For binary frames, the screenshot field is populated.
+        """
+        self._conn.socket.settimeout(timeout)
+        try:
+            frame = self._conn.recv()
+        except TimeoutError:
+            raise QirabotTimeoutError("WebSocket receive timed out")
+
+        if isinstance(frame, str):
+            # Text frame: pure JSON
+            data = json.loads(frame)
+            return StepMessage(data=data)
+
+        # Binary frame: [2-byte JSON length] [JSON] [PNG]
+        if len(frame) < 2:
+            return StepMessage(data={})
+        json_len = struct.unpack("!H", frame[:2])[0]
+        json_bytes = frame[2 : 2 + json_len]
+        screenshot = frame[2 + json_len :]
+        data = json.loads(json_bytes)
+        return StepMessage(data=data, screenshot=screenshot if screenshot else None)
+
+    def close(self) -> None:
+        """Close the WebSocket connection."""
+        try:
+            self._conn.close()
+        except Exception:
+            pass
+
+    def __enter__(self) -> WSConnection:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

qirabot-0.1.0/src/qirabot/actions.py

@@ -0,0 +1,156 @@
+"""Action definitions for Qirabot SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Action:
+    """A device action to execute.
+
+    Use the class methods to create actions instead of constructing directly.
+    """
+
+    type: str
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        return {"type": self.type, "params": self.params}
+
+    # ── Click ──
+
+    @classmethod
+    def click(cls, locate: str) -> Action:
+        return cls(type="click", params={"locate": locate})
+
+    @classmethod
+    def double_click(cls, locate: str) -> Action:
+        return cls(type="double_click", params={"locate": locate})
+
+    @classmethod
+    def right_click(cls, locate: str) -> Action:
+        return cls(type="right_click", params={"locate": locate})
+
+    @classmethod
+    def hover(cls, locate: str) -> Action:
+        return cls(type="hover", params={"locate": locate})
+
+    # ── Text Input ──
+
+    @classmethod
+    def type_text(cls, locate: str, content: str) -> Action:
+        return cls(type="type_text", params={"locate": locate, "content": content})
+
+    @classmethod
+    def type_direct(cls, content: str) -> Action:
+        return cls(type="type_text_direct", params={"content": content})
+
+    @classmethod
+    def clear_text(cls, locate: str) -> Action:
+        return cls(type="clear_text", params={"locate": locate})
+
+    @classmethod
+    def press_key(cls, key: str) -> Action:
+        return cls(type="press_key", params={"key": key})
+
+    # ── Navigation ──
+
+    @classmethod
+    def navigate(cls, url: str) -> Action:
+        return cls(type="navigate", params={"url": url})
+
+    @classmethod
+    def scroll(cls, direction: str = "down", distance: int | None = None) -> Action:
+        params: dict[str, Any] = {"direction": direction}
+        if distance is not None:
+            params["distance"] = distance
+        return cls(type="scroll", params=params)
+
+    @classmethod
+    def scroll_at(cls, locate: str, direction: str = "down", distance: int | None = None) -> Action:
+        params: dict[str, Any] = {"locate": locate, "direction": direction}
+        if distance is not None:
+            params["distance"] = distance
+        return cls(type="scroll_at", params=params)
+
+    @classmethod
+    def swipe(
+        cls,
+        direction: str,
+        locate: str | None = None,
+        distance: int | None = None,
+        duration_ms: int = 500,
+    ) -> Action:
+        params: dict[str, Any] = {"direction": direction, "durationMs": duration_ms}
+        if locate is not None:
+            params["locate"] = locate
+        if distance is not None:
+            params["distance"] = distance
+        return cls(type="swipe", params=params)
+
+    # ── Wait ──
+
+    @classmethod
+    def wait(cls, duration_ms: int) -> Action:
+        return cls(type="wait", params={"durationMs": duration_ms})
+
+    @classmethod
+    def wait_for(
+        cls,
+        assertion: str,
+        timeout_ms: int,
+        check_interval_ms: int = 1000,
+    ) -> Action:
+        return cls(
+            type="wait_for",
+            params={
+                "assertion": assertion,
+                "timeoutMs": timeout_ms,
+                "checkInterval": check_interval_ms,
+            },
+        )
+
+    # ── Screenshot ──
+
+    @classmethod
+    def take_screenshot(cls) -> Action:
+        return cls(type="take_screenshot")
+
+    # ── AI ──
+
+    @classmethod
+    def extract(cls, instruction: str, variable: str = "result", value_type: str = "string") -> Action:
+        return cls(
+            type="extract",
+            params={"instruction": instruction, "variable": variable, "valueType": value_type},
+        )
+
+    @classmethod
+    def verify(cls, assertion: str) -> Action:
+        return cls(type="assert", params={"assertion": assertion})
+
+    @classmethod
+    def ai(cls, instruction: str, max_steps: int = 10, model_alias: str | None = None, language: str | None = None) -> Action:
+        params: dict[str, Any] = {"instruction": instruction, "maxSteps": max_steps}
+        if model_alias is not None:
+            params["modelAlias"] = model_alias
+        if language is not None:
+            params["language"] = language
+        return cls(type="ai_decision", params=params)
+
+    @classmethod
+    def search(cls, locate: str, content: str) -> Action:
+        return cls(type="search", params={"locate": locate, "text": content})
+
+    # ── App Control ──
+
+    @classmethod
+    def start_app(cls, package: str) -> Action:
+        return cls(type="start_app", params={"package": package})
+
+    @classmethod
+    def stop_app(cls, package: str) -> Action:
+        return cls(type="stop_app", params={"package": package})

qirabot-0.1.0/src/qirabot/client.py

@@ -0,0 +1,231 @@
+"""Main client for Qirabot SDK."""
+
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from qirabot._transport import Transport
+from qirabot.actions import Action
+from qirabot.exceptions import QirabotTimeoutError
+from qirabot.task_context import TaskContext
+
+
+@dataclass
+class DeviceInfo:
+    """Device information."""
+
+    id: str
+    name: str
+    platform: str
+    online: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DeviceInfo:
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            platform=data.get("platform", ""),
+            online=data.get("online", False),
+        )
+
+
+@dataclass
+class TaskResult:
+    """Result of a completed task."""
+
+    id: str
+    status: str
+    current_step: int = 0
+    source: str = ""
+    error: str = ""
+    steps: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "succeeded"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TaskResult:
+        return cls(
+            id=data.get("id", ""),
+            status=data.get("status", ""),
+            current_step=data.get("currentStep", 0),
+            source=data.get("source", ""),
+            error=data.get("error", ""),
+        )
+
+
+class Qirabot:
+    """Qirabot SDK client.
+
+    Usage::
+
+        bot = Qirabot("qk_xxx", base_url="https://app.qirabot.com")
+        with bot.task("device-id") as t:
+            t.click("Login button")
+            t.type("username", "admin")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://app.qirabot.com",
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+    ):
+        self._transport = Transport(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+        )
+
+    def devices(self) -> list[DeviceInfo]:
+        """List all devices for the current user."""
+        resp = self._transport.request("GET", "/devices")
+        return [DeviceInfo.from_dict(d) for d in resp] if isinstance(resp, list) else []
+
+    def active_devices(self) -> list[DeviceInfo]:
+        """List online devices for the current user."""
+        resp = self._transport.request("GET", "/devices/active")
+        return [DeviceInfo.from_dict(d) for d in resp] if isinstance(resp, list) else []
+
+    def submit(
+        self,
+        device_id: str = "",
+        *,
+        actions: list[Action] | None = None,
+        instruction: str = "",
+        model_alias: str = "",
+        language: str = "",
+        max_steps: int = 10,
+        screenshot_mode: str = "cloud",
+    ) -> str:
+        """Submit actions for autonomous execution and return the task ID immediately.
+
+        Use ``wait()`` to poll for completion.
+
+        Args:
+            device_id: The device to run on (optional if sandbox is configured).
+            actions: List of actions to execute sequentially.
+            instruction: Shorthand for a single AI action. Mutually exclusive with ``actions``.
+            model_alias: Optional AI model alias.
+            language: Optional language (e.g. "zh", "en").
+            max_steps: Max steps for AI instruction (default 10).
+            screenshot_mode: "cloud" (default) or "none".
+
+        Returns:
+            The task ID string.
+        """
+        if instruction and actions:
+            raise ValueError("Cannot specify both 'actions' and 'instruction'")
+        if not instruction and not actions:
+            raise ValueError("Must specify either 'actions' or 'instruction'")
+
+        if instruction:
+            steps = [Action.ai(instruction, max_steps=max_steps, model_alias=model_alias or None, language=language or None)]
+        else:
+            steps = actions  # type: ignore[assignment]
+
+        body: dict[str, Any] = {
+            "actions": [a.to_dict() for a in steps],
+        }
+        if device_id:
+            body["deviceId"] = device_id
+        if model_alias:
+            body["modelAlias"] = model_alias
+        if language:
+            body["language"] = language
+        if screenshot_mode != "cloud":
+            body["screenshotMode"] = screenshot_mode
+
+        resp = self._transport.post("/sdk/tasks/submit", body)
+        return resp["taskId"]
+
+    def wait(
+        self,
+        task_id: str,
+        timeout: float = 120.0,
+        poll_interval: float = 3.0,
+    ) -> TaskResult:
+        """Poll until a submitted task reaches a terminal state.
+
+        Args:
+            task_id: The task ID returned by ``submit()``.
+            timeout: Maximum seconds to wait (default 120).
+            poll_interval: Seconds between polls (default 3).
+
+        Returns:
+            A :class:`TaskResult` with the final status and steps.
+
+        Raises:
+            QirabotTimeoutError: If the task does not complete within the timeout.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            resp = self._transport.request("GET", f"/tasks/{task_id}")
+            status = resp.get("status", "")
+            if status not in ("pending", "running"):
+                result = TaskResult.from_dict(resp)
+                steps_resp = self._transport.request("GET", f"/tasks/{task_id}/steps")
+                if isinstance(steps_resp, list):
+                    result.steps = steps_resp
+                return result
+            if time.monotonic() >= deadline:
+                raise QirabotTimeoutError(f"Task {task_id} did not complete within {timeout}s")
+            time.sleep(poll_interval)
+
+    @contextmanager
+    def task(
+        self,
+        device_id: str,
+        model_alias: str = "",
+        language: str = "",
+        screenshot_mode: str = "cloud",
+    ) -> Iterator[TaskContext]:
+        """Create a task on a device and return an interactive context.
+
+        Args:
+            device_id: The device to connect to.
+            model_alias: Optional AI model alias to use (default: server default).
+            language: Optional language for AI responses (e.g. "zh", "en", "ja").
+            screenshot_mode: Screenshot storage mode:
+                - "cloud": store to cloud, return path (default)
+                - "inline": no cloud storage, send binary via WebSocket
+                - "none": no screenshots stored or returned
+
+        Yields:
+            A TaskContext that auto-completes on exit.
+        """
+        body: dict[str, Any] = {"deviceId": device_id}
+        if model_alias:
+            body["modelAlias"] = model_alias
+        if language:
+            body["language"] = language
+        if screenshot_mode != "cloud":
+            body["screenshotMode"] = screenshot_mode
+
+        resp = self._transport.post("/sdk/tasks", body)
+        task_id = resp["taskId"]
+
+        ctx = TaskContext(
+            transport=self._transport,
+            task_id=task_id,
+            device_id=device_id,
+            screenshot_mode=screenshot_mode,
+        )
+        with ctx:
+            yield ctx
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._transport.close()
+
+    def __enter__(self) -> Qirabot:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

qirabot-0.1.0/src/qirabot/exceptions.py

@@ -0,0 +1,90 @@
+"""Exceptions for Qirabot SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class QirabotError(Exception):
+    """Base exception for all Qirabot SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        status_code: int | None = None,
+    ):
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(QirabotError):
+    """API key is missing or invalid (401)."""
+
+
+class DeviceBusyError(QirabotError):
+    """Device already has a running task (409)."""
+
+
+class DeviceOfflineError(QirabotError):
+    """Device is not connected (400)."""
+
+
+class LeaseExpiredError(QirabotError):
+    """Task lease has expired (409)."""
+
+
+class ActionError(QirabotError):
+    """A device action failed during task."""
+
+
+class QirabotTimeoutError(QirabotError):
+    """Operation timed out (client-side)."""
+
+
+# Error code → exception class mapping
+_ERROR_CODE_MAP: dict[str, type[QirabotError]] = {
+    "auth.api_key_missing": AuthenticationError,
+    "auth.api_key_invalid": AuthenticationError,
+    "sdk.device_busy": DeviceBusyError,
+    "sdk.device_not_connected": DeviceOfflineError,
+    "sdk.task_not_found": QirabotError,
+    "sdk.task_not_active": QirabotError,
+    "sdk.lease_expired": LeaseExpiredError,
+}
+
+_STATUS_CODE_MAP: dict[int, type[QirabotError]] = {
+    401: AuthenticationError,
+    409: DeviceBusyError,
+}
+
+
+def raise_for_error(status_code: int, data: dict[str, Any]) -> None:
+    """Raise the appropriate exception for an error response.
+
+    Supports both flat format {"code": "...", "message": "..."}
+    and nested format {"error": {"code": "...", "message": "..."}}.
+    """
+    error = data.get("error", {})
+    if isinstance(error, str):
+        message = error or data.get("message", f"Request failed with status {status_code}")
+        code = data.get("code")
+    elif error:
+        message = error.get("message", f"Request failed with status {status_code}")
+        code = error.get("code")
+    else:
+        message = data.get("message", f"Request failed with status {status_code}")
+        code = data.get("code")
+
+    if code and code in _ERROR_CODE_MAP:
+        raise _ERROR_CODE_MAP[code](message, code=code, status_code=status_code)
+
+    exc_cls = _STATUS_CODE_MAP.get(status_code, QirabotError)
+    raise exc_cls(message, code=code, status_code=status_code)

qirabot-0.1.0/src/qirabot/task_context.py

@@ -0,0 +1,377 @@
+"""Task context for Qirabot SDK."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, TYPE_CHECKING
+
+from qirabot.actions import Action
+from qirabot.exceptions import ActionError
+
+if TYPE_CHECKING:
+    from qirabot._transport import Transport, WSConnection
+
+logger = logging.getLogger("qirabot")
+
+_HEARTBEAT_INTERVAL = 15.0  # seconds
+
+
+@dataclass
+class StepEvent:
+    """Emitted after each step completes."""
+
+    number: int
+    action: str
+    status: str
+    output: str | None = None
+    decision: str | None = None
+    error: str | None = None
+    action_duration_time_ms: int = 0
+    step_duration_ms: int = 0
+
+
+@dataclass
+class ScreenshotEvent:
+    """Emitted when a step has a screenshot available.
+
+    For inline mode, ``data`` contains the raw PNG bytes directly.
+    For cloud mode, use ``save()`` or ``to_bytes()`` to download from the server.
+    """
+
+    number: int
+    task_id: str
+    data: bytes | None = None
+    _transport: Transport | None = field(default=None, repr=False)
+
+    def save(self, local_path: str) -> None:
+        """Save the screenshot to a local file."""
+        img = self.to_bytes()
+        with open(local_path, "wb") as f:
+            f.write(img)
+
+    def to_bytes(self) -> bytes:
+        """Return raw screenshot bytes.
+
+        For inline mode, returns the data directly.
+        For cloud mode, downloads from the server.
+        """
+        if self.data is not None:
+            return self.data
+        if self._transport is None:
+            raise RuntimeError("Transport not available")
+        return self._transport.get_bytes(
+            f"/screenshots?taskId={self.task_id}&step={self.number}"
+        )
+
+
+# Type alias for event handlers
+EventHandler = Callable[..., Any]
+
+
+class TaskContext:
+    """Interactive task context for step-by-step device automation.
+
+    Created by ``Qirabot.task()``. Use as a context manager::
+
+        with bot.task("device-id") as t:
+            t.click("Login button")
+            t.type("username", "admin")
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        task_id: str,
+        device_id: str,
+        screenshot_mode: str = "cloud",
+    ):
+        self._transport = transport
+        self._task_id = task_id
+        self._device_id = device_id
+        self._screenshot_mode = screenshot_mode
+        self._heartbeat_stop: threading.Event | None = None
+        self._heartbeat_thread: threading.Thread | None = None
+        self._listeners: dict[str, list[EventHandler]] = {}
+        self._ws: WSConnection | None = None
+
+    @property
+    def task_id(self) -> str:
+        return self._task_id
+
+    @property
+    def device_id(self) -> str:
+        return self._device_id
+
+    # ── Event system ──
+
+    def on(self, event: str, handler: EventHandler) -> TaskContext:
+        """Register an event listener.
+
+        Supported events:
+            - ``"step"``: called with :class:`StepEvent` after each step completes.
+            - ``"screenshot"``: called with :class:`ScreenshotEvent` when a screenshot is available.
+
+        Returns self for chaining.
+        """
+        self._listeners.setdefault(event, []).append(handler)
+        return self
+
+    def off(self, event: str, handler: EventHandler | None = None) -> TaskContext:
+        """Remove event listener(s).
+
+        If handler is None, removes all listeners for the event.
+        """
+        if handler is None:
+            self._listeners.pop(event, None)
+        elif event in self._listeners:
+            self._listeners[event] = [h for h in self._listeners[event] if h is not handler]
+        return self
+
+    def _emit(self, event: str, data: Any) -> None:
+        for handler in self._listeners.get(event, []):
+            try:
+                handler(data)
+            except Exception:
+                logger.exception("Error in %s event handler", event)
+
+    # ── Context manager ──
+
+    def __enter__(self) -> TaskContext:
+        self._start_heartbeat()
+        self._ws = self._transport.ws_connect(
+            f"/sdk/tasks/{self._task_id}/ws"
+        )
+        return self
+
+    def __exit__(self, exc_type: type | None, exc_val: BaseException | None, exc_tb: Any) -> None:
+        self._stop_heartbeat()
+        try:
+            if exc_type is None:
+                self.complete()
+            elif issubclass(exc_type, KeyboardInterrupt):
+                self.cancel()
+            else:
+                self.complete(status="failed", error_message=str(exc_val) if exc_val else "")
+        except Exception:
+            logger.exception("Failed to complete task during cleanup")
+        if self._ws is not None:
+            try:
+                self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    # ── Device actions ──
+
+    def click(self, locate: str, **kw: Any) -> None:
+        self._act(Action.click(locate), **kw)
+
+    def double_click(self, locate: str, **kw: Any) -> None:
+        self._act(Action.double_click(locate), **kw)
+
+    def right_click(self, locate: str, **kw: Any) -> None:
+        self._act(Action.right_click(locate), **kw)
+
+    def hover(self, locate: str, **kw: Any) -> None:
+        self._act(Action.hover(locate), **kw)
+
+    def type(self, locate: str, content: str, **kw: Any) -> None:
+        self._act(Action.type_text(locate, content), **kw)
+
+    def type_direct(self, content: str, **kw: Any) -> None:
+        self._act(Action.type_direct(content), **kw)
+
+    def clear_text(self, locate: str, **kw: Any) -> None:
+        self._act(Action.clear_text(locate), **kw)
+
+    def press_key(self, key: str, **kw: Any) -> None:
+        self._act(Action.press_key(key), **kw)
+
+    def navigate(self, url: str, **kw: Any) -> None:
+        self._act(Action.navigate(url), **kw)
+
+    def scroll(self, direction: str = "down", distance: int | None = None, **kw: Any) -> None:
+        self._act(Action.scroll(direction, distance), **kw)
+
+    def scroll_at(self, locate: str, direction: str = "down", distance: int | None = None, **kw: Any) -> None:
+        self._act(Action.scroll_at(locate, direction, distance), **kw)
+
+    def swipe(self, direction: str, locate: str | None = None, distance: int | None = None, duration_ms: int = 500, **kw: Any) -> None:
+        self._act(Action.swipe(direction, locate, distance, duration_ms), **kw)
+
+    def wait(self, duration_ms: int, **kw: Any) -> None:
+        self._act(Action.wait(duration_ms), **kw)
+
+    def wait_for(self, assertion: str, timeout_ms: int, check_interval_ms: int = 1000, **kw: Any) -> None:
+        self._act(Action.wait_for(assertion, timeout_ms, check_interval_ms), **kw)
+
+    def screenshot(self, path: str | None = None, **kw: Any) -> bytes | None:
+        """Take a screenshot.
+
+        Args:
+            path: If provided, save the screenshot to this local file path.
+
+        Returns:
+            Screenshot bytes if path is None, otherwise None.
+        """
+        captured: dict[str, Any] = {}
+
+        def _capture_screenshot(event: ScreenshotEvent) -> None:
+            captured["event"] = event
+
+        self.on("screenshot", _capture_screenshot)
+        try:
+            self._act(Action.take_screenshot(), **kw)
+        finally:
+            self.off("screenshot", _capture_screenshot)
+
+        event = captured.get("event")
+        if event is not None:
+            img = event.to_bytes()
+            if path:
+                with open(path, "wb") as f:
+                    f.write(img)
+                return None
+            return img
+        return None
+
+    def extract(self, instruction: str, variable: str = "result", value_type: str = "string", **kw: Any) -> str:
+        """Extract data from the screen using AI.
+
+        Returns:
+            The extracted value as a string.
+        """
+        result = self._act(Action.extract(instruction, variable, value_type), **kw)
+        return result.get("output", "") if result else ""
+
+    def verify(self, assertion: str, **kw: Any) -> bool:
+        """Verify a condition on the screen using AI.
+
+        Returns:
+            True if the assertion passes, False otherwise.
+        """
+        result = self._act(Action.verify(assertion), **kw)
+        output = result.get("output", "") if result else ""
+        return output.lower() in ("true", "pass", "yes", "1") if output else False
+
+    def ai(self, instruction: str, max_steps: int = 10, model_alias: str | None = None, language: str | None = None, **kw: Any) -> str:
+        """Let AI autonomously complete a task.
+
+        Args:
+            instruction: Natural language description of the goal.
+            max_steps: Maximum number of steps AI can take.
+            model_alias: Optional model alias to override the session default.
+            language: Optional language to override the session default (e.g. "zh", "en").
+
+        Returns:
+            The output string from the AI task, or empty string if none.
+        """
+        result = self._act(Action.ai(instruction, max_steps, model_alias=model_alias, language=language), **kw)
+        return result.get("output", "") if result else ""
+
+    def search(self, locate: str, content: str, **kw: Any) -> None:
+        self._act(Action.search(locate, content), **kw)
+
+    def start_app(self, package: str, **kw: Any) -> None:
+        self._act(Action.start_app(package), **kw)
+
+    def stop_app(self, package: str, **kw: Any) -> None:
+        self._act(Action.stop_app(package), **kw)
+
+    # ── Execution lifecycle ──
+
+    def complete(self, status: str = "succeeded", error_message: str = "") -> None:
+        """Complete the task and release the device."""
+        body: dict[str, Any] = {"status": status}
+        if error_message:
+            body["errorMessage"] = error_message
+        try:
+            self._transport.post(f"/sdk/tasks/{self._task_id}/complete", body)
+        except Exception:
+            logger.exception("Failed to complete task %s", self._task_id)
+
+    def cancel(self) -> None:
+        """Cancel the task and release the device."""
+        try:
+            self._transport.delete(f"/sdk/tasks/{self._task_id}")
+        except Exception:
+            logger.exception("Failed to cancel task %s", self._task_id)
+
+    # ── Internal ──
+
+    def _act(self, action: Action, timeout: float = 300.0, on_step: EventHandler | None = None) -> dict[str, Any] | None:
+        """Execute a single action via WebSocket and return the final result data."""
+        if self._ws is None:
+            raise RuntimeError("Task not started. Use as a context manager.")
+
+        self._ws.send_action(action.to_dict())
+
+        last_result: dict[str, Any] = {}
+
+        while True:
+            msg = self._ws.receive(timeout=timeout)
+            msg_type = msg.data.get("type", "")
+
+            if msg_type == "step":
+                step_event = StepEvent(
+                    number=msg.data.get("stepNumber", 0),
+                    action=msg.data.get("actionType", ""),
+                    status=msg.data.get("status", ""),
+                    output=msg.data.get("output"),
+                    decision=msg.data.get("decision"),
+                    error=msg.data.get("error"),
+                    action_duration_time_ms=msg.data.get("actionDurationTimeMs", 0),
+                    step_duration_ms=msg.data.get("stepDurationMs", 0),
+                )
+                self._emit("step", step_event)
+                if on_step:
+                    on_step(step_event)
+
+                # Emit screenshot event if available (inline binary or cloud path)
+                has_screenshot = msg.screenshot is not None
+                screenshot_path = msg.data.get("screenshotPath")
+                if has_screenshot or screenshot_path:
+                    screenshot_event = ScreenshotEvent(
+                        number=step_event.number,
+                        task_id=self._task_id,
+                        data=msg.screenshot,
+                        _transport=self._transport if screenshot_path else None,
+                    )
+                    self._emit("screenshot", screenshot_event)
+
+            elif msg_type == "result":
+                last_result = msg.data
+                if not msg.data.get("success", False) and not msg.data.get("finished", False):
+                    error_msg = msg.data.get("error", "Action failed")
+                    raise ActionError(error_msg, code="action.failed")
+                break
+
+            elif msg_type == "error":
+                error_msg = msg.data.get("error", "Unknown error")
+                raise ActionError(error_msg, code="ws.error")
+
+        return last_result
+
+    def _start_heartbeat(self) -> None:
+        self._heartbeat_stop = threading.Event()
+        self._heartbeat_thread = threading.Thread(
+            target=self._heartbeat_loop,
+            daemon=True,
+        )
+        self._heartbeat_thread.start()
+
+    def _stop_heartbeat(self) -> None:
+        if self._heartbeat_stop:
+            self._heartbeat_stop.set()
+        if self._heartbeat_thread:
+            self._heartbeat_thread.join(timeout=5.0)
+
+    def _heartbeat_loop(self) -> None:
+        assert self._heartbeat_stop is not None
+        while not self._heartbeat_stop.wait(_HEARTBEAT_INTERVAL):
+            try:
+                self._transport.post(f"/sdk/tasks/{self._task_id}/heartbeat")
+            except Exception:
+                logger.warning("Heartbeat failed for task %s", self._task_id)

qirabot-0.1.0/src/qirabot.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: qirabot
+Version: 0.1.0
+Summary: Official Python SDK for Qirabot - AI-powered device automation
+Author-email: Qirabot Team <support@qirabot.com>
+License-Expression: MIT
+Keywords: qirabot,automation,testing,ai,sdk,rpa
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"

qirabot-0.1.0/src/qirabot.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+src/qirabot/__init__.py
+src/qirabot/_transport.py
+src/qirabot/actions.py
+src/qirabot/client.py
+src/qirabot/exceptions.py
+src/qirabot/task_context.py
+src/qirabot.egg-info/PKG-INFO
+src/qirabot.egg-info/SOURCES.txt
+src/qirabot.egg-info/dependency_links.txt
+src/qirabot.egg-info/requires.txt
+src/qirabot.egg-info/top_level.txt

qirabot-0.1.0/src/qirabot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qirabot-0.1.0/src/qirabot.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.27.0
+websockets>=13.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+mypy>=1.0.0
+ruff>=0.1.0

qirabot-0.1.0/src/qirabot.egg-info/top_level.txt

@@ -0,0 +1 @@
+qirabot