glasswarp 0.1.0__tar.gz

glasswarp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.DS_Store
+# Local demo captures (not part of the published package)
+gemini_*.jpg
+paint_*.jpg
+examples/vp0_out/

glasswarp-0.1.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 — 2026-07-22
+
+Initial public release on PyPI.
+
+- `GlasswarpClient` over Platform API `/v1/*` (`https://signal.glasswarp.com`)
+- Sessions, observe / screenshot, native input, app launch/kill
+- Grounding helpers (`som_annotate`, `targets_from_grid`, `click_target`) via optional `glasswarp[grounding]`
+- Typed package (`py.typed`)

glasswarp-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Woodrow Stores LLC
+
+   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.

glasswarp-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: glasswarp
+Version: 0.1.0
+Summary: Eyes and hands for AI agents on real Windows — Python SDK for the Glasswarp Platform API.
+Project-URL: Homepage, https://www.glasswarp.com
+Project-URL: Documentation, https://docs.glasswarp.com
+Project-URL: Repository, https://github.com/saferelay/project-x
+Project-URL: Issues, https://github.com/saferelay/project-x/issues
+Project-URL: Changelog, https://github.com/saferelay/project-x/blob/main/sdk/python/CHANGELOG.md
+Author-email: Woodrow Stores LLC <hello@glasswarp.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agents,automation,computer-use,glasswarp,mcp,screenshot,windows
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: grounding
+Requires-Dist: pillow>=10; extra == 'grounding'
+Description-Content-Type: text/markdown
+
+# Glasswarp Python SDK
+
+See any screen. Control any PC. One API.
+
+Glasswarp gives your agent **eyes and hands** on a real Windows machine; you
+supply the **brain** (model, prompts, CV, solvers). Example task logic lives under
+`examples/` and outcome-named starters under `templates/` — not in the platform.
+Public plans: Free / Builder / Growth / Enterprise. Game Mode at `/play` is a frozen
+demo of the same capture pipeline.
+
+```bash
+pip install glasswarp
+# optional SoM / image helpers:
+pip install "glasswarp[grounding]"
+```
+
+> **Publish status:** packaging targets PyPI as `glasswarp` (`0.1.0`). Until the
+> first upload lands, install from this repo: `pip install -e sdk/python`.
+> Operator steps: [`docs/PYPI_PUBLISH.md`](../../docs/PYPI_PUBLISH.md).
+
+Want Claude / Cursor with **no project code**? Use the remote MCP server instead —
+[glasswarp.com/mcp](https://www.glasswarp.com/mcp) ·
+[docs](https://docs.glasswarp.com/get-started/mcp).
+
+## Quickstart
+
+```python
+from glasswarp import GlasswarpClient
+
+gw = GlasswarpClient(api_key="gw_live_sk_...")
+
+# List your rigs
+rigs = gw.list_rigs()
+rig = rigs[0]
+
+# Start a desktop session
+session = gw.create_session(rig_id=rig.id)
+
+# Take a screenshot (returns JPEG bytes)
+screenshot = gw.screenshot(session.session_id)
+with open("screen.jpg", "wb") as f:
+    f.write(screenshot.jpeg)
+
+# Send input
+gw.click(session.session_id, x=500, y=400)
+gw.type_text(session.session_id, "Hello from Python!")
+gw.key_press(session.session_id, "Enter")
+
+# End the session
+gw.end_session(session.session_id)
+```
+
+## Configuration
+
+| Parameter | Env var | Default |
+|-----------|---------|---------|
+| `api_key` | `GLASSWARP_API_KEY` | (required) |
+| `base_url` | `GLASSWARP_BASE_URL` | `https://signal.glasswarp.com` |
+
+## API reference
+
+### Rigs
+
+- `list_rigs()` — all rigs accessible to this key
+- `get_rig(rig_id)` — single rig detail
+
+### Sessions
+
+- `create_session(rig_id, mode="desktop")` — start a session
+- `get_session(session_id)` — current status
+- `list_sessions()` — all active sessions
+- `end_session(session_id)` — end and trigger safety_restore
+
+### Visual
+
+- `screenshot(session_id, max_width=None, quality=None, x=y=w=h=None)` — JPEG; optional ROI crop
+- `dirty_rects(session_id)` — accumulated DXGI dirty rects since last poll (VP0)
+- `list_targets(session_id)` — sparse click targets from host UIA (P8); empty if none
+- `observe(session_id, mark=True, targets=None, …)` — one RTT: JPEG + dirty + targets (SoM when marked)
+
+### Grounding (SoM)
+
+Agents should click **targets**, not guessed pixels:
+
+```python
+from glasswarp import targets_from_grid, som_annotate
+
+# Host UIA targets (P8) or client CV/grid:
+targets = targets_from_grid(x0=100, y0=200, x1=900, y1=800, rows=8, cols=8)
+obs = gw.observe(session.session_id, max_width=1280, mark=True, targets=targets)
+# obs.jpeg is Set-of-Mark annotated; model returns target id →
+gw.click_target(session.session_id, "12", targets=targets)
+```
+
+- `som_annotate(jpeg, targets, native_width=…, native_height=…)` — draw numbered marks (needs `pip install pillow`)
+- `targets_from_grid(…)` — build cell targets for a rectangular board
+- `click_target(session_id, target_or_id, targets=…)` — click bbox center
+
+### Apps
+
+- `launch_app(session_id, path, args=None)` — spawn a process on the rig (returns `pid`)
+- `kill_app(session_id, pid=None)` — kill session-launched apps (`pid` optional)
+
+### Input
+
+- `send_input(session_id, events)` — batch input events
+- `click(session_id, x, y, button)` — click at coordinates
+- `type_text(session_id, text)` — type a string
+- `key_press(session_id, key)` — press a key
+- `move_mouse(session_id, x, y)` — move cursor
+- `scroll(session_id, dx, dy)` — scroll
+
+### Stream
+
+- `stream(session_id)` — WebRTC signaling credentials for a live 60fps feed
+
+## Templates
+
+Outcome-named starters in `templates/` (observe → think → act → verify):
+
+- `templates/observe_think_act/` — minimal agent-loop skeleton
+- `templates/notepad_type/` — Notepad via UIA + type
+- `templates/live_view_hitl/` — hold a session for Console Live View
+
+## Examples
+
+See `examples/` for complete runnable scripts:
+
+- `quickstart.py` — connect, screenshot, click, type, disconnect
+- `vp0_smoke.py` — dirty rects + ROI screenshot smoke
+- `vp0_observe.py` — shared VP0 helper (dirty skip + ROI coalesce) for agent loops
+- `paint_mark_demo.py` — **an agent draws a themed GLASSWARP outline in Paint** (custom colors + native drag). See [Paint quickstart](../../docs/QUICKSTART_PAINT.md).
+- `paint_mona_lisa_demo.py` — **an agent reproduces the Mona Lisa in Paint** (observe→think→act→verify: vision placement, UIA colors, tile fills, Save As→Desktop). VNC-hard differentiator. See [Mona Lisa quickstart](../../docs/QUICKSTART_MONA_LISA.md).
+- `notepad_uia_demo.py` — Notepad via UIA targets + type. See [Notepad quickstart](../../docs/QUICKSTART_NOTEPAD.md).
+- `minesweeper_solver_demo.py` — Minesweeper demo (CV + solver). See [quickstart](../../docs/QUICKSTART_MINESWEEPER.md).
+- `gemini_agent_loop.py` — Minesweeper demo with Gemini + SoM → `click_target` → verify
+- `claude_agent_loop.py` — observe → Claude → act; VP0 on by default (`VP0=0` for full frames)
+
+## License
+
+Apache-2.0

glasswarp-0.1.0/README.md

@@ -0,0 +1,141 @@
+# Glasswarp Python SDK
+
+See any screen. Control any PC. One API.
+
+Glasswarp gives your agent **eyes and hands** on a real Windows machine; you
+supply the **brain** (model, prompts, CV, solvers). Example task logic lives under
+`examples/` and outcome-named starters under `templates/` — not in the platform.
+Public plans: Free / Builder / Growth / Enterprise. Game Mode at `/play` is a frozen
+demo of the same capture pipeline.
+
+```bash
+pip install glasswarp
+# optional SoM / image helpers:
+pip install "glasswarp[grounding]"
+```
+
+> **Publish status:** packaging targets PyPI as `glasswarp` (`0.1.0`). Until the
+> first upload lands, install from this repo: `pip install -e sdk/python`.
+> Operator steps: [`docs/PYPI_PUBLISH.md`](../../docs/PYPI_PUBLISH.md).
+
+Want Claude / Cursor with **no project code**? Use the remote MCP server instead —
+[glasswarp.com/mcp](https://www.glasswarp.com/mcp) ·
+[docs](https://docs.glasswarp.com/get-started/mcp).
+
+## Quickstart
+
+```python
+from glasswarp import GlasswarpClient
+
+gw = GlasswarpClient(api_key="gw_live_sk_...")
+
+# List your rigs
+rigs = gw.list_rigs()
+rig = rigs[0]
+
+# Start a desktop session
+session = gw.create_session(rig_id=rig.id)
+
+# Take a screenshot (returns JPEG bytes)
+screenshot = gw.screenshot(session.session_id)
+with open("screen.jpg", "wb") as f:
+    f.write(screenshot.jpeg)
+
+# Send input
+gw.click(session.session_id, x=500, y=400)
+gw.type_text(session.session_id, "Hello from Python!")
+gw.key_press(session.session_id, "Enter")
+
+# End the session
+gw.end_session(session.session_id)
+```
+
+## Configuration
+
+| Parameter | Env var | Default |
+|-----------|---------|---------|
+| `api_key` | `GLASSWARP_API_KEY` | (required) |
+| `base_url` | `GLASSWARP_BASE_URL` | `https://signal.glasswarp.com` |
+
+## API reference
+
+### Rigs
+
+- `list_rigs()` — all rigs accessible to this key
+- `get_rig(rig_id)` — single rig detail
+
+### Sessions
+
+- `create_session(rig_id, mode="desktop")` — start a session
+- `get_session(session_id)` — current status
+- `list_sessions()` — all active sessions
+- `end_session(session_id)` — end and trigger safety_restore
+
+### Visual
+
+- `screenshot(session_id, max_width=None, quality=None, x=y=w=h=None)` — JPEG; optional ROI crop
+- `dirty_rects(session_id)` — accumulated DXGI dirty rects since last poll (VP0)
+- `list_targets(session_id)` — sparse click targets from host UIA (P8); empty if none
+- `observe(session_id, mark=True, targets=None, …)` — one RTT: JPEG + dirty + targets (SoM when marked)
+
+### Grounding (SoM)
+
+Agents should click **targets**, not guessed pixels:
+
+```python
+from glasswarp import targets_from_grid, som_annotate
+
+# Host UIA targets (P8) or client CV/grid:
+targets = targets_from_grid(x0=100, y0=200, x1=900, y1=800, rows=8, cols=8)
+obs = gw.observe(session.session_id, max_width=1280, mark=True, targets=targets)
+# obs.jpeg is Set-of-Mark annotated; model returns target id →
+gw.click_target(session.session_id, "12", targets=targets)
+```
+
+- `som_annotate(jpeg, targets, native_width=…, native_height=…)` — draw numbered marks (needs `pip install pillow`)
+- `targets_from_grid(…)` — build cell targets for a rectangular board
+- `click_target(session_id, target_or_id, targets=…)` — click bbox center
+
+### Apps
+
+- `launch_app(session_id, path, args=None)` — spawn a process on the rig (returns `pid`)
+- `kill_app(session_id, pid=None)` — kill session-launched apps (`pid` optional)
+
+### Input
+
+- `send_input(session_id, events)` — batch input events
+- `click(session_id, x, y, button)` — click at coordinates
+- `type_text(session_id, text)` — type a string
+- `key_press(session_id, key)` — press a key
+- `move_mouse(session_id, x, y)` — move cursor
+- `scroll(session_id, dx, dy)` — scroll
+
+### Stream
+
+- `stream(session_id)` — WebRTC signaling credentials for a live 60fps feed
+
+## Templates
+
+Outcome-named starters in `templates/` (observe → think → act → verify):
+
+- `templates/observe_think_act/` — minimal agent-loop skeleton
+- `templates/notepad_type/` — Notepad via UIA + type
+- `templates/live_view_hitl/` — hold a session for Console Live View
+
+## Examples
+
+See `examples/` for complete runnable scripts:
+
+- `quickstart.py` — connect, screenshot, click, type, disconnect
+- `vp0_smoke.py` — dirty rects + ROI screenshot smoke
+- `vp0_observe.py` — shared VP0 helper (dirty skip + ROI coalesce) for agent loops
+- `paint_mark_demo.py` — **an agent draws a themed GLASSWARP outline in Paint** (custom colors + native drag). See [Paint quickstart](../../docs/QUICKSTART_PAINT.md).
+- `paint_mona_lisa_demo.py` — **an agent reproduces the Mona Lisa in Paint** (observe→think→act→verify: vision placement, UIA colors, tile fills, Save As→Desktop). VNC-hard differentiator. See [Mona Lisa quickstart](../../docs/QUICKSTART_MONA_LISA.md).
+- `notepad_uia_demo.py` — Notepad via UIA targets + type. See [Notepad quickstart](../../docs/QUICKSTART_NOTEPAD.md).
+- `minesweeper_solver_demo.py` — Minesweeper demo (CV + solver). See [quickstart](../../docs/QUICKSTART_MINESWEEPER.md).
+- `gemini_agent_loop.py` — Minesweeper demo with Gemini + SoM → `click_target` → verify
+- `claude_agent_loop.py` — observe → Claude → act; VP0 on by default (`VP0=0` for full frames)
+
+## License
+
+Apache-2.0

glasswarp-0.1.0/glasswarp/__init__.py

@@ -0,0 +1,48 @@
+"""Glasswarp Python SDK — see any screen, control any PC, one API."""
+
+from glasswarp.client import GlasswarpClient, GlasswarpError
+from glasswarp.grounding import som_annotate, targets_from_grid
+from glasswarp.types import (
+    Rig,
+    Session,
+    ApiKey,
+    Screenshot,
+    Target,
+    ObserveResult,
+    InputEvent,
+    MouseMove,
+    MouseClick,
+    MouseDown,
+    MouseUp,
+    MouseScroll,
+    KeyPress,
+    KeyDown,
+    KeyUp,
+    TypeText,
+    StreamConnection,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "GlasswarpClient",
+    "GlasswarpError",
+    "Rig",
+    "Session",
+    "ApiKey",
+    "Screenshot",
+    "Target",
+    "ObserveResult",
+    "som_annotate",
+    "targets_from_grid",
+    "InputEvent",
+    "MouseMove",
+    "MouseClick",
+    "MouseDown",
+    "MouseUp",
+    "MouseScroll",
+    "KeyPress",
+    "KeyDown",
+    "KeyUp",
+    "TypeText",
+    "StreamConnection",
+]

glasswarp-0.1.0/glasswarp/client.py

@@ -0,0 +1,454 @@
+"""Glasswarp API client."""
+
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import asdict
+from typing import Optional, Sequence, Union
+
+import httpx
+
+from glasswarp.types import (
+    ApiKey,
+    InputEvent,
+    ObserveResult,
+    Rig,
+    Screenshot,
+    Session,
+    StreamConnection,
+    Target,
+)
+
+DEFAULT_BASE_URL = "https://signal.glasswarp.com"
+
+
+class GlasswarpError(Exception):
+    """Raised when the API returns a non-2xx status."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        self.message = message
+        super().__init__(f"[{status}] {message}")
+
+
+class GlasswarpClient:
+    """Synchronous client for the Glasswarp Platform API.
+
+    Usage::
+
+        from glasswarp import GlasswarpClient
+
+        gw = GlasswarpClient(api_key="gw_live_sk_...")
+        rigs = gw.list_rigs()
+        session = gw.create_session(rig_id=rigs[0].id)
+        screenshot = gw.screenshot(session.session_id)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("GLASSWARP_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required — pass it or set GLASSWARP_API_KEY"
+            )
+        self.base_url = (base_url or os.environ.get("GLASSWARP_BASE_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "GlasswarpClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ── Helpers ──────────────────────────────────────────────────────────
+
+    def _json(self, response: httpx.Response) -> dict:
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                msg = body.get("error", response.text)
+            except Exception:
+                msg = response.text
+            raise GlasswarpError(response.status_code, msg)
+        return response.json()
+
+    # ── Rigs ─────────────────────────────────────────────────────────────
+
+    def list_rigs(self) -> list[Rig]:
+        """List all rigs accessible to this API key."""
+        data = self._json(self._http.get("/v1/rigs"))
+        return [Rig(**r) for r in data.get("rigs", [])]
+
+    def get_rig(self, rig_id: str) -> Rig:
+        """Get details for a single rig."""
+        data = self._json(self._http.get(f"/v1/rigs/{rig_id}"))
+        return Rig(**data)
+
+    # ── Sessions ─────────────────────────────────────────────────────────
+
+    def create_session(
+        self,
+        rig_id: str,
+        mode: str = "desktop",
+        *,
+        idle_timeout_seconds: int | None = None,
+    ) -> Session:
+        """Start a new API session on a rig.
+
+        ``idle_timeout_seconds`` (60–3600, default 900 / 15m) is how long the
+        session may sit with no screenshot/observe/input before the server ends
+        it automatically. Longer idle = more wall-clock billed minutes.
+        """
+        body: dict = {"rig_id": rig_id, "mode": mode}
+        if idle_timeout_seconds is not None:
+            body["idle_timeout_seconds"] = idle_timeout_seconds
+        data = self._json(self._http.post("/v1/sessions", json=body))
+        return Session(**data)
+
+    def get_session(self, session_id: str) -> Session:
+        """Get the current state of a session."""
+        data = self._json(self._http.get(f"/v1/sessions/{session_id}"))
+        return Session(**data)
+
+    def list_sessions(self) -> list[Session]:
+        """List all active sessions for this API key's owner."""
+        data = self._json(self._http.get("/v1/sessions"))
+        return [Session(**s) for s in data.get("sessions", [])]
+
+    def end_session(self, session_id: str, *, keep_apps: bool = False) -> dict:
+        """End a session (triggers safety_restore on the host).
+
+        By default, apps launched via :meth:`launch_app` are killed. Pass
+        ``keep_apps=True`` to leave them running (useful for demos that should
+        leave Paint or Notepad open on the desktop).
+        """
+        path = f"/v1/sessions/{session_id}"
+        if keep_apps:
+            path += "?keep_apps=1"
+        return self._json(self._http.request("DELETE", path))
+
+    # ── Screenshot ───────────────────────────────────────────────────────
+
+    def screenshot(
+        self,
+        session_id: str,
+        *,
+        max_width: int | None = None,
+        quality: int | None = None,
+        x: int | None = None,
+        y: int | None = None,
+        w: int | None = None,
+        h: int | None = None,
+    ) -> Screenshot:
+        """Capture a JPEG of the current screen (from the host last-frame buffer).
+
+        Capture stays at native desktop resolution (including 4K). Pass
+        ``max_width`` / ``quality`` to downscale on the host for faster LLM
+        ingest. Pass ``x,y,w,h`` for a ROI crop in native capture coords (VP0).
+        Click coordinates should use ``native_width`` / ``native_height``.
+        """
+        params: dict[str, int] = {}
+        if max_width is not None:
+            params["max_width"] = max_width
+        if quality is not None:
+            params["quality"] = quality
+        if x is not None and y is not None and w is not None and h is not None:
+            params["x"] = x
+            params["y"] = y
+            params["w"] = w
+            params["h"] = h
+
+        response = self._http.get(
+            f"/v1/sessions/{session_id}/screenshot",
+            params=params or None,
+        )
+        if response.status_code >= 400:
+            try:
+                msg = response.json().get("error", response.text)
+            except Exception:
+                msg = response.text
+            raise GlasswarpError(response.status_code, msg)
+
+        width = int(response.headers.get("X-Screenshot-Width", "0"))
+        height = int(response.headers.get("X-Screenshot-Height", "0"))
+        return Screenshot(
+            jpeg=response.content,
+            width=width,
+            height=height,
+            timestamp=int(response.headers.get("X-Screenshot-Timestamp", "0")),
+            native_width=int(
+                response.headers.get("X-Screenshot-Native-Width", str(width))
+            ),
+            native_height=int(
+                response.headers.get("X-Screenshot-Native-Height", str(height))
+            ),
+        )
+
+    def dirty_rects(self, session_id: str) -> dict:
+        """Return accumulated DXGI dirty rects since last poll (VP0).
+
+        Each rect is ``[x, y, w, h]`` in capture-buffer coordinates. Empty
+        ``rects`` means no visual change since the previous take — safe to
+        skip a vision model call.
+        """
+        return self._json(self._http.get(f"/v1/sessions/{session_id}/dirty"))
+
+    def list_targets(self, session_id: str) -> list[Target]:
+        """Return sparse click targets (VP0.5). Empty until host UIA (P8)."""
+        data = self._json(self._http.get(f"/v1/sessions/{session_id}/targets"))
+        return [_parse_target(t) for t in (data.get("targets") or [])]
+
+    def observe(
+        self,
+        session_id: str,
+        *,
+        max_width: int | None = None,
+        quality: int | None = None,
+        x: int | None = None,
+        y: int | None = None,
+        w: int | None = None,
+        h: int | None = None,
+        mark: bool = True,
+        targets: Sequence[Target] | None = None,
+    ) -> ObserveResult:
+        """One-RTT observe: JPEG + dirty + targets (VP0.5 grounding).
+
+        If ``targets`` is passed (e.g. client CV/grid), those override the
+        host list and are used for optional SoM marking when ``mark=True``.
+        """
+        params: dict[str, int] = {}
+        if max_width is not None:
+            params["max_width"] = max_width
+        if quality is not None:
+            params["quality"] = quality
+        if x is not None and y is not None and w is not None and h is not None:
+            params["x"] = x
+            params["y"] = y
+            params["w"] = w
+            params["h"] = h
+        if mark:
+            params["mark"] = 1
+
+        data = self._json(
+            self._http.get(
+                f"/v1/sessions/{session_id}/observe",
+                params=params or None,
+            )
+        )
+        jpeg = base64.b64decode(data["jpeg_base64"])
+        host_targets = [_parse_target(t) for t in (data.get("targets") or [])]
+        resolved = list(targets) if targets is not None else host_targets
+        marked = bool(data.get("marked"))
+        if mark and resolved and (targets is not None or not marked):
+            from glasswarp.grounding import som_annotate
+
+            jpeg = som_annotate(
+                jpeg,
+                resolved,
+                native_width=int(data.get("native_width") or data.get("width") or 1),
+                native_height=int(
+                    data.get("native_height") or data.get("height") or 1
+                ),
+            )
+            marked = True
+
+        return ObserveResult(
+            jpeg=jpeg,
+            width=int(data.get("width") or 0),
+            height=int(data.get("height") or 0),
+            native_width=int(data.get("native_width") or data.get("width") or 0),
+            native_height=int(
+                data.get("native_height") or data.get("height") or 0
+            ),
+            timestamp=int(data.get("timestamp") or 0),
+            dirty=data.get("dirty") or {},
+            targets=resolved,
+            marked=marked,
+        )
+
+    def click_target(
+        self,
+        session_id: str,
+        target: Union[Target, str],
+        *,
+        targets: Sequence[Target] | None = None,
+        button: str = "left",
+    ) -> dict:
+        """Click the center of a grounding target (by object or id)."""
+        if isinstance(target, Target):
+            t = target
+        else:
+            pool = list(targets or [])
+            if not pool:
+                pool = self.list_targets(session_id)
+            match = next((x for x in pool if x.id == target), None)
+            if match is None:
+                raise GlasswarpError(400, f"Unknown target id: {target}")
+            t = match
+        cx, cy = t.center
+        return self.click(session_id, x=cx, y=cy, button=button)
+
+    # ── Stream ───────────────────────────────────────────────────────────
+
+    def stream(self, session_id: str) -> StreamConnection:
+        """Get WebRTC signaling credentials for a live 60fps video stream.
+
+        Returns connection details including a ready-to-use WebSocket URL.
+        Connect to ``connect_url``, send an SDP OFFER, receive an ANSWER,
+        and exchange ICE candidates to start receiving H.264 video.
+        """
+        data = self._json(self._http.get(f"/v1/sessions/{session_id}/stream"))
+        return StreamConnection(**data)
+
+    # ── Apps ─────────────────────────────────────────────────────────────
+
+    def launch_app(
+        self,
+        session_id: str,
+        path: str,
+        args: list[str] | None = None,
+    ) -> dict:
+        """Spawn an application on the remote rig (e.g. ``notepad.exe``).
+
+        Returns ``{"ok": True, "pid": <int>}``. Tracked PIDs are killed on
+        ``end_session`` or via :meth:`kill_app`.
+        """
+        body: dict = {"path": path}
+        if args is not None:
+            body["args"] = args
+        return self._json(
+            self._http.post(f"/v1/sessions/{session_id}/app/launch", json=body)
+        )
+
+    def kill_app(self, session_id: str, pid: int | None = None) -> dict:
+        """Kill apps launched via :meth:`launch_app` in this session.
+
+        Pass ``pid`` to kill one process; omit to kill all session-launched apps.
+        """
+        body: dict = {}
+        if pid is not None:
+            body["pid"] = pid
+        return self._json(
+            self._http.post(f"/v1/sessions/{session_id}/app/kill", json=body)
+        )
+
+    # ── Input ────────────────────────────────────────────────────────────
+
+    def send_input(self, session_id: str, events: list[InputEvent]) -> dict:
+        """Send input events (mouse, keyboard) to the session's rig."""
+        payload = [asdict(e) for e in events]
+        return self._json(
+            self._http.post(
+                f"/v1/sessions/{session_id}/input",
+                json={"events": payload},
+            )
+        )
+
+    def click(
+        self,
+        session_id: str,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        button: str = "left",
+    ) -> dict:
+        """Convenience: click at (x, y)."""
+        from glasswarp.types import MouseClick
+        return self.send_input(session_id, [MouseClick(button=button, x=x, y=y)])  # type: ignore[arg-type]
+
+    def type_text(self, session_id: str, text: str) -> dict:
+        """Convenience: type a string."""
+        from glasswarp.types import TypeText
+        return self.send_input(session_id, [TypeText(text=text)])
+
+    def key_press(self, session_id: str, key: str) -> dict:
+        """Convenience: press and release a key."""
+        from glasswarp.types import KeyPress
+        return self.send_input(session_id, [KeyPress(key=key)])
+
+    def move_mouse(self, session_id: str, x: int, y: int) -> dict:
+        """Convenience: move the mouse cursor."""
+        from glasswarp.types import MouseMove
+        return self.send_input(session_id, [MouseMove(x=x, y=y)])
+
+    def mouse_down(
+        self,
+        session_id: str,
+        x: int,
+        y: int,
+        button: str = "left",
+    ) -> dict:
+        """Press a mouse button at (x, y) without releasing (start of a drag)."""
+        from glasswarp.types import MouseDown
+        return self.send_input(
+            session_id, [MouseDown(button=button, x=x, y=y)]  # type: ignore[arg-type]
+        )
+
+    def mouse_up(
+        self,
+        session_id: str,
+        x: int,
+        y: int,
+        button: str = "left",
+    ) -> dict:
+        """Release a mouse button at (x, y) (end of a drag)."""
+        from glasswarp.types import MouseUp
+        return self.send_input(
+            session_id, [MouseUp(button=button, x=x, y=y)]  # type: ignore[arg-type]
+        )
+
+    def drag(
+        self,
+        session_id: str,
+        x0: int,
+        y0: int,
+        x1: int,
+        y1: int,
+        *,
+        button: str = "left",
+        steps: int = 12,
+    ) -> dict:
+        """Drag from (x0,y0) to (x1,y1) with intermediate moves (native coords)."""
+        from glasswarp.types import MouseDown, MouseMove, MouseUp
+
+        steps = max(2, steps)
+        events: list = [MouseDown(button=button, x=x0, y=y0)]
+        for i in range(1, steps + 1):
+            t = i / steps
+            events.append(
+                MouseMove(
+                    x=int(round(x0 + (x1 - x0) * t)),
+                    y=int(round(y0 + (y1 - y0) * t)),
+                )
+            )
+        events.append(MouseUp(button=button, x=x1, y=y1))
+        return self.send_input(session_id, events)  # type: ignore[arg-type]
+
+    def scroll(self, session_id: str, dx: int = 0, dy: int = 0) -> dict:
+        """Convenience: scroll the mouse wheel."""
+        from glasswarp.types import MouseScroll
+        return self.send_input(session_id, [MouseScroll(dx=dx, dy=dy)])
+
+
+def _parse_target(raw: dict) -> Target:
+    return Target(
+        id=str(raw["id"]),
+        x=int(raw["x"]),
+        y=int(raw["y"]),
+        w=int(raw["w"]),
+        h=int(raw["h"]),
+        role=raw.get("role"),
+        name=raw.get("name"),
+        source=raw.get("source"),
+    )

glasswarp-0.1.0/glasswarp/grounding.py

@@ -0,0 +1,111 @@
+"""Set-of-Mark (SoM) helpers for agent grounding."""
+
+from __future__ import annotations
+
+import io
+from typing import Sequence
+
+from glasswarp.types import Target
+
+
+def som_annotate(
+    jpeg: bytes,
+    targets: Sequence[Target],
+    *,
+    native_width: int,
+    native_height: int,
+    style: str = "badge",
+) -> bytes:
+    """Draw numbered marks on a JPEG for VLM grounding.
+
+    Target bboxes are in *native capture* coords; the JPEG may be downscaled.
+    ``style``:
+      - ``badge`` (default): cyan box + opaque red id badge (good for sparse UIA)
+      - ``corner``: thin outline + tiny corner id — keeps cell contents readable
+        (needed for dense grids like Minesweeper)
+
+    Requires Pillow (``pip install pillow``).
+    """
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+    except ImportError as e:
+        raise ImportError(
+            "som_annotate requires Pillow — pip install pillow"
+        ) from e
+
+    img = Image.open(io.BytesIO(jpeg)).convert("RGB")
+    draw = ImageDraw.Draw(img)
+    jw, jh = img.size
+    sx = jw / max(1, native_width)
+    sy = jh / max(1, native_height)
+
+    corner = style == "corner"
+    font_size = 9 if corner else 12
+    try:
+        font = ImageFont.truetype("/System/Library/Fonts/Helvetica.ttc", font_size)
+    except Exception:
+        font = ImageFont.load_default()
+
+    for t in targets:
+        x0 = t.x * sx
+        y0 = t.y * sy
+        x1 = (t.x + t.w) * sx
+        y1 = (t.y + t.h) * sy
+        outline = (0, 180, 255) if corner else (0, 200, 255)
+        draw.rectangle([x0, y0, x1, y1], outline=outline, width=1 if corner else 2)
+        label = t.id
+        bx, by = x0 + 1, y0 + 1
+        if corner:
+            tw = max(8, 5 * len(label))
+            th = 10
+            # Semi-transparent feel via dark red (small — leaves cell center free)
+            draw.rectangle([bx, by, bx + tw, by + th], fill=(200, 30, 30))
+            draw.text((bx + 1, by), label, fill=(255, 255, 255), font=font)
+        else:
+            tw = max(10, 7 * len(label))
+            th = 14
+            draw.rectangle([bx, by, bx + tw, by + th], fill=(255, 40, 40))
+            draw.text((bx + 2, by + 1), label, fill=(255, 255, 255), font=font)
+
+    out = io.BytesIO()
+    img.save(out, format="JPEG", quality=85)
+    return out.getvalue()
+
+
+def targets_from_grid(
+    *,
+    x0: int,
+    y0: int,
+    x1: int,
+    y1: int,
+    rows: int,
+    cols: int,
+    id_prefix: str = "",
+    source: str = "grid",
+) -> list[Target]:
+    """Build one target per cell of a rectangular grid (native coords)."""
+    cell_w = (x1 - x0) / max(1, cols)
+    cell_h = (y1 - y0) / max(1, rows)
+    out: list[Target] = []
+    n = 1
+    for r in range(rows):
+        for c in range(cols):
+            tx = int(round(x0 + c * cell_w))
+            ty = int(round(y0 + r * cell_h))
+            tw = int(round(cell_w))
+            th = int(round(cell_h))
+            tid = f"{id_prefix}{n}" if id_prefix else str(n)
+            out.append(
+                Target(
+                    id=tid,
+                    x=tx,
+                    y=ty,
+                    w=tw,
+                    h=th,
+                    role="cell",
+                    name=f"{r},{c}",
+                    source=source,
+                )
+            )
+            n += 1
+    return out

glasswarp-0.1.0/glasswarp/types.py

@@ -0,0 +1,166 @@
+"""Data types for the Glasswarp SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union
+
+
+@dataclass
+class Rig:
+    id: str
+    name: Optional[str]
+    online: bool
+    gpu: Optional[str]
+    os: Optional[str]
+    api_access_enabled: bool
+    has_active_session: bool
+
+
+@dataclass
+class Session:
+    session_id: str
+    rig_id: str
+    mode: Literal["desktop", "app"]
+    status: Literal["active", "ended", "failed"]
+    started_at: Optional[str] = None
+    action_count: int = 0
+    idle_timeout_seconds: Optional[int] = None
+
+
+@dataclass
+class ApiKey:
+    id: str
+    name: str
+    key_prefix: str
+    environment: str
+    scopes: list[str] = field(default_factory=list)
+    allowed_rig_ids: Optional[list[str]] = None
+    created_at: Optional[str] = None
+    last_used_at: Optional[str] = None
+    revoked_at: Optional[str] = None
+
+
+@dataclass
+class Screenshot:
+    """`width`/`height` are the JPEG size; `native_*` is the desktop capture size."""
+
+    jpeg: bytes
+    width: int
+    height: int
+    timestamp: int
+    native_width: int = 0
+    native_height: int = 0
+
+
+@dataclass
+class Target:
+    """Sparse click target in *native capture* coordinates (VP0.5 grounding)."""
+
+    id: str
+    x: int
+    y: int
+    w: int
+    h: int
+    role: Optional[str] = None
+    name: Optional[str] = None
+    source: Optional[str] = None  # uia | cv | grid | client
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return self.x + self.w // 2, self.y + self.h // 2
+
+
+@dataclass
+class ObserveResult:
+    """One-RTT observe: JPEG + dirty + targets (VP0.5)."""
+
+    jpeg: bytes
+    width: int
+    height: int
+    native_width: int
+    native_height: int
+    timestamp: int
+    dirty: dict[str, Any] = field(default_factory=dict)
+    targets: list[Target] = field(default_factory=list)
+    marked: bool = False
+
+
+@dataclass
+class StreamConnection:
+    """WebRTC signaling credentials for a live video stream."""
+    signaling_url: str
+    viewer_token: str
+    rig_id: str
+    session_id: str
+    connect_url: str
+    instructions: dict[str, str] = field(default_factory=dict)
+
+
+# ── Input events ─────────────────────────────────────────────────────────
+
+@dataclass
+class MouseMove:
+    x: int
+    y: int
+    type: str = "mouse_move"
+
+
+@dataclass
+class MouseClick:
+    button: Literal["left", "right", "middle"] = "left"
+    x: Optional[int] = None
+    y: Optional[int] = None
+    type: str = "mouse_click"
+
+
+@dataclass
+class MouseDown:
+    button: Literal["left", "right", "middle"] = "left"
+    x: Optional[int] = None
+    y: Optional[int] = None
+    type: str = "mouse_down"
+
+
+@dataclass
+class MouseUp:
+    button: Literal["left", "right", "middle"] = "left"
+    x: Optional[int] = None
+    y: Optional[int] = None
+    type: str = "mouse_up"
+
+
+@dataclass
+class MouseScroll:
+    dx: int = 0
+    dy: int = 0
+    type: str = "mouse_scroll"
+
+
+@dataclass
+class KeyPress:
+    key: str = ""
+    type: str = "key_press"
+
+
+@dataclass
+class KeyDown:
+    key: str = ""
+    type: str = "key_down"
+
+
+@dataclass
+class KeyUp:
+    key: str = ""
+    type: str = "key_up"
+
+
+@dataclass
+class TypeText:
+    text: str = ""
+    type: str = "type_text"
+
+
+InputEvent = Union[
+    MouseMove, MouseClick, MouseDown, MouseUp, MouseScroll, KeyPress, KeyDown, KeyUp, TypeText
+]

glasswarp-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "glasswarp"
+version = "0.1.0"
+description = "Eyes and hands for AI agents on real Windows — Python SDK for the Glasswarp Platform API."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+  { name = "Woodrow Stores LLC", email = "hello@glasswarp.com" },
+]
+keywords = [
+  "glasswarp",
+  "computer-use",
+  "windows",
+  "agents",
+  "screenshot",
+  "automation",
+  "mcp",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+grounding = [
+  "pillow>=10",
+]
+dev = [
+  "pytest>=7",
+  "pytest-httpx>=0.21",
+  "build>=1.2",
+  "twine>=5",
+]
+
+[project.urls]
+Homepage = "https://www.glasswarp.com"
+Documentation = "https://docs.glasswarp.com"
+Repository = "https://github.com/saferelay/project-x"
+Issues = "https://github.com/saferelay/project-x/issues"
+Changelog = "https://github.com/saferelay/project-x/blob/main/sdk/python/CHANGELOG.md"
+
+[tool.hatch.build]
+# Keep the published sdist lean — package + docs only (no demo JPEGs / examples).
+[tool.hatch.build.targets.sdist]
+include = [
+  "/glasswarp",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+  "/CHANGELOG.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["glasswarp"]